Package: simple-salesforce-wrapper
Simple Salesforce is a basic Salesforce.com REST API client built for Python 2.6, 2.7, 3.3 and 3.4. The goal is to provide a very low-level interface to the REST Resource and APEX API, returning a dictionary of the API JSON response.Simple Salesforce wrapper is a small wrapper, that does not do much except adds reconnection upon session expiry and handles the SOAP call for converting a Lead to a ContactYou can find out more regarding the format of the results in theOfficial Salesforce.com REST API Documentation99% of the Documentation is plagiarized from simple-salesforce. This module does not do much, it just serves me well.
Simple Salesforce is available here:https://github.com/simple-salesforce/simple-salesforceSpecial thanks to Pavol Bujna to help make this work after 4 years of inactivity :-)Installationpip3installsimple_salesforce_wrapperExamplesThere are two ways to gain access to SalesforceThe first is to simply pass the domain of your Salesforce instance and an access token straight toSalesforce()For example:fromsimple_salesforceimportSalesforcesf=Salesforce(instance='na1.salesforce.com',session_id='')If you have the full URL of your instance (perhaps including the schema, as is included in the OAuth2 request process), you can pass that in instead usinginstance_url:fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(instance_url='https://na1.salesforce.com',session_id='')There are also three means of authentication, one that uses username, password and security token; one that uses IP filtering, username, password  and organizationId; and the other that uses a private key to sign a JWT.To login using the security token method, simply include the Salesforce method and pass in your Salesforce username, password and token (this is usually provided when you change your password):fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(username='myemail@example.com',password='password',security_token='token')To login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(password='password',username='myemail@example.com',organizationId='OrgId')To login using the JWT method, use your Salesforce username, consumer key from your app, and private key:fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(username='myemail@example.com',consumer_key='XYZ',privatekey_file='filename.key')If you’d like to enter a sandbox, simply adddomain='test'to yourSalesforce()call.For example:fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(username='myemail@example.com.sandbox',password='password',security_token='token',domain='test')Note that specifying if you want to use a domain is only necessary if you are using the built-in username/password/security token authentication and is used exclusively during the authentication step.If you’d like to keep track where your API calls are coming from, simply addclient_id='MyApp'to yourSalesforce()call.fromsimple_salesforce_wrapperimportSalesforcesf=Salesforce(username='myemail@example.com.sandbox',password='password',security_token='token',client_id='My App',domain='test')If you view the API calls in your Salesforce instance by Client Id it will be prefixed withRestForce/, for exampleRestForce/My App.When instantiating aSalesforceobject, it’s also possible to include an
instance ofrequests.Session. This is to allow for specialized
session handling not otherwise exposed by simple_salesforce.For example:fromsimple_salesforce_wrapperimportSalesforceimportrequestssession=requests.Session()# manipulate the session instance (optional)sf=Salesforce(username='user@example.com',password='password',organizationId='OrgId',session=session)Record ManagementTo create a new ‘Contact’ in Salesforce:sf.Contact.create({'LastName':'Smith','Email':'example@example.com'})This will return a dictionary such as{u'errors': [], u'id': u'003e0000003GuNXAA0', u'success': True}To get a dictionary with all the information regarding that record, use:contact=sf.Contact.get('003e0000003GuNXAA0')To get a dictionary with all the information regarding that record, using acustomfield that was defined as External ID:contact=sf.Contact.get_by_custom_id('My_Custom_ID__c','22')To change that contact’s last name from ‘Smith’ to ‘Jones’ and add a first name of ‘John’ use:sf.Contact.update('003e0000003GuNXAA0',{'LastName':'Jones','FirstName':'John'})To delete the contact:sf.Contact.delete('003e0000003GuNXAA0')To retrieve a list of Contact records deleted over the past 10 days (datetimes are required to be in UTC):importpytzimportdatetimeend=datetime.datetime.now(pytz.UTC)# we need to use UTC as salesforce API requires this!sf.Contact.deleted(end-datetime.timedelta(days=10),end)To retrieve a list of Contact records updated over the past 10 days (datetimes are required to be in UTC):importpytzimportdatetimeend=datetime.datetime.now(pytz.UTC)# we need to use UTC as salesforce API requires thissf.Contact.updated(end-datetime.timedelta(days=10),end)Note that Update, Delete and Upsert actions return the associatedSalesforce HTTP Status CodeUse the same format to create any record, including ‘Account’, ‘Opportunity’, and ‘Lead’.
Make sure to have all the required fields for any entry. TheSalesforce APIhas all objects found under ‘Reference -> Standard Objects’ and the required fields can be found there.QueriesIt’s also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).SOQL queries are done via:sf.query("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")If, due to an especially large result, Salesforce adds anextRecordsUrlto your query result, such as"nextRecordsUrl" :"/services/data/v26.0/query/01gD0000002HU6KIAW-2000", you can pull the additional results with either the ID or the full URL (if using the full URL, you must pass ‘True’ as your second argument)sf.query_more("01gD0000002HU6KIAW-2000")sf.query_more("/services/data/v26.0/query/01gD0000002HU6KIAW-2000",True)As a convenience, to retrieve all of the results in a single local method call usesf.query_all("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")Whilequery_allmaterializes the whole result into a Python list,query_all_iterreturns an iterator, which allows you to lazily process each element separatelydata=sf.query_all_iter("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")forrowindata:process(row)Values used in SOQL queries can be quoted and escaped usingformat_soql:sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName ={}","Jones"))sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName ={last_name}",last_name="Jones"))sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName IN{names}",names=["Smith","Jones"]))To skip quoting and escaping for one value while still using the format string, use:literal:sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Income > {:literal}","USD100"))To escape a substring used in a LIKE expression while being able to use % around it, use:like:sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Name LIKE '{:like}%'","Jones"))SOSL queries are done via:sf.search("FIND{Jones}")There is also ‘Quick Search’, which inserts your query inside the {} in the SOSL syntax. Be careful, there is no escaping!sf.quick_search("Jones")Search and Quick Search returnNoneif there are no records, otherwise they return a dictionary of search results.More details about syntax is available on theSalesforce Query Language Documentation Developer WebsiteLead Conversion(convert_success,convert_response)=sf.convert_lead(lead_id=lead_sfid,account_id=account_sfid)Convert Lead returns a tuple containing a boolean status and a convert_response.
If convert_success is True then so is convert_response is the contact ID
If convert_success is False then so is convert_response is the error code e.g. CANNOT_UPDATE_CONVERTED_LEADOther OptionsTo insert or update (upsert) a record using an external ID, use:sf.Contact.upsert('customExtIdField__c/11999',{'LastName':'Smith','Email':'smith@example.com'})To format an external ID that could contain non-URL-safe characters, use:external_id=format_external_id('customExtIdField__c','this/that & the other')To retrieve basic metadata use:sf.Contact.metadata()To retrieve a description of the object, use:sf.Contact.describe()To retrieve a description of the record layout of an object by its record layout unique id, use:sf.Contact.describe_layout('39wmxcw9r23r492')To retrieve a list of top level description of instance metadata, user:sf.describe()forxinsf.describe()["sobjects"]:printx["label"]Using BulkYou can use this library to access Bulk API functions. The data element can be a list of records of any size and by default batch sizes are 10,000 records and run in parrallel concurrency mode. To set the batch size for insert, upsert, delete, hard_delete, and update use the batch_size argument. To set the concurrency mode for the salesforce job the use_serial argument can be set to use_serial=True.Create new records:data=[{'LastName':'Smith','Email':'example@example.com'},{'LastName':'Jones','Email':'test@test.com'}]sf.bulk.Contact.insert(data,batch_size=10000,use_serial=True)Update existing records:data=[{'Id':'0000000000AAAAA','Email':'examplenew@example.com'},{'Id':'0000000000BBBBB','Email':'testnew@test.com'}]sf.bulk.Contact.update(data,batch_size=10000,use_serial=True)Upsert records:data=[{'Id':'0000000000AAAAA','Email':'examplenew2@example.com'},{'Email':'foo@foo.com'}]sf.bulk.Contact.upsert(data,'Id',batch_size=10000,use_serial=True)Query records:query='SELECT Id, Name FROM Account LIMIT 10'sf.bulk.Account.query(query)To retrieve large amounts of data, usequery='SELECT Id, Name FROM Account'# generator on the results pagefetch_results=sf.bulk.Account.query(query,lazy_operation=True)# the generator provides the list of results for every call to next()all_results=[]forlist_resultsinfetch_results:all_results.extend(list_results)Query all records:QueryAll will return records that have been deleted because of a merge or delete. QueryAll will also return information about archived Task and Event records.query='SELECT Id, Name FROM Account LIMIT 10'sf.bulk.Account.query_all(query)To retrieve large amounts of data, usequery='SELECT Id, Name FROM Account'# generator on the results pagefetch_results=sf.bulk.Account.query_all(query,lazy_operation=True)# the generator provides the list of results for every call to next()all_results=[]forlist_resultsinfetch_results:all_results.extend(list_results)Delete records (soft deletion):data=[{'Id':'0000000000AAAAA'}]sf.bulk.Contact.delete(data,batch_size=10000,use_serial=True)Hard deletion:data=[{'Id':'0000000000BBBBB'}]sf.bulk.Contact.hard_delete(data,batch_size=10000,use_serial=True)Using ApexYou can also use this library to call custom Apex methods:payload={"activity":[{"user":"12345","action":"update page","time":"2014-04-21T13:00:15Z"}]}result=sf.apexecute('User/Activity',method='POST',data=payload)This would call the endpointhttps://<instance>.salesforce.com/services/apexrest/User/Activitywithdata=as
the body content encoded withjson.dumpsYou can read more about Apex on theForce.com Apex Code Developer’s GuideAdditional FeaturesThere are a few helper classes that are used internally and available to you.Included in them areSalesforceLogin, which takes in a username, password, security token, optional version and optional domain and returns a tuple of(session_id, sf_instance)wheresession_idis the session ID to use for authentication to Salesforce andsf_instanceis the domain of the instance of Salesforce to use for the session.For example, to use SalesforceLogin for a sandbox account you’d use:fromsimple_salesforce_wrapperimportSalesforceLoginsession_id,instance=SalesforceLogin(username='myemail@example.com.sandbox',password='password',security_token='token',domain='test')Simply leave off the final domain if you do not wish to use a sandbox.Also exposed is theSFTypeclass, which is used internally by the__getattr__()method in theSalesforce()class and represents a specific SObject type.SFTyperequiresobject_name(i.e.Contact),session_id(an authentication ID),sf_instance(hostname of your Salesforce instance), and an optionalsf_versionTo add a Contact using the default version of the API you’d use:fromsimple_salesforce_wrapperimportSFTypecontact=SFType('Contact','sesssionid','na1.salesforce.com')contact.create({'LastName':'Smith','Email':'example@example.com'})To use a proxy server between your client and the SalesForce endpoint, use the proxies argument when creating SalesForce object.
The proxy argument is the same as what requests uses, a map of scheme to proxy URL:proxies={"http":"http://10.10.1.10:3128","https":"http://10.10.1.10:1080",}SalesForce(instance='na1.salesforce.com',session_id='',proxies=proxies)All results are returned as JSON converted OrderedDict to preserve order of keys from REST responses.Helpful Datetime ResourcesA list of helpful resources when working with datetime/dates from SalesforceConvert SFDC Datetime to Datetime or Date object
.. code-block:: pythonimport datetime
# Formatting to SFDC datetime
formatted_datetime =  datetime.datetime.strptime(x, “%Y-%m-%dT%H:%M:%S.%f%z”)#Formatting to SFDC date
formatted_date = datetime.strptime(x, “%Y-%m-%d”)Helpful Pandas ResourcesA list of helpful resources when working with Pandas and simple-salesforceGenerate list for SFDC Query “IN” operations from a Pandas Dataframeimportpandasaspddf=pd.DataFrame([{'Id':1},{'Id':2},{'Id':3}])defdataframe_to_sfdc_list(df,column):df_list=df[column].unique()df_list=[str(x)forxindf_list]df_list=','.join("'"+item+"'"foritemindf_list)returndf_listsf.query(format_soql("SELECT Id, Email FROM Contact WHERE Id IN ({})",dataframe_to_sfdc_list(df,column)))Generate Pandas Dataframe from SFDC API Query (ex.query,query_all)importpandasaspdsf.query("SELECT Id, Email FROM Contact")df=pd.DataFrame(data['records']).drop(['attributes'],axis=1)Generate Pandas Dataframe from SFDC Bulk API Query (ex.bulk.Account.query)importpandasaspdsf.bulk.Account.query("SELECT Id, Email FROM Contact")df=pd.DataFrame.from_dict(data,orient='columns').drop('attributes',axis=1)LicenseThis package is released under an open source Apache 2.0 license likehttps://github.com/simple-salesforce/simple-salesforce