PKG-INFO 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388
  1. Metadata-Version: 1.2
  2. Name: simple-salesforce
  3. Version: 0.74.2
  4. Summary: A basic Salesforce.com REST API client.
  5. Home-page: https://github.com/simple-salesforce/simple-salesforce
  6. Author: Nick Catalano
  7. Author-email: nickcatal@gmail.com
  8. Maintainer: Demian Brecht
  9. Maintainer-email: demianbrecht@gmail.com
  10. License: Apache 2.0
  11. Description: *****************
  12. Simple Salesforce
  13. *****************
  14. .. image:: https://api.travis-ci.org/simple-salesforce/simple-salesforce.svg?branch=master
  15. :target: https://travis-ci.org/simple-salesforce/simple-salesforce
  16. .. image:: https://readthedocs.org/projects/simple-salesforce/badge/?version=latest
  17. :target: http://simple-salesforce.readthedocs.io/en/latest/?badge=latest
  18. :alt: Documentation Status
  19. Simple Salesforce is a basic Salesforce.com REST API client built for Python 2.6, 2.7, 3.3, 3.4, 3.5, and 3.6. 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.
  20. You can find out more regarding the format of the results in the `Official Salesforce.com REST API Documentation`_
  21. .. _Official Salesforce.com REST API Documentation: http://www.salesforce.com/us/developer/docs/api_rest/index.htm
  22. Examples
  23. --------
  24. There are two ways to gain access to Salesforce
  25. The first is to simply pass the domain of your Salesforce instance and an access token straight to ``Salesforce()``
  26. For example:
  27. .. code-block:: python
  28. from simple_salesforce import Salesforce
  29. sf = Salesforce(instance='na1.salesforce.com', session_id='')
  30. 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 using ``instance_url``:
  31. .. code-block:: python
  32. from simple_salesforce import Salesforce
  33. sf = Salesforce(instance_url='https://na1.salesforce.com', session_id='')
  34. There are also two means of authentication, one that uses username, password and security token and the other that uses IP filtering, username, password and organizationId
  35. 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):
  36. .. code-block:: python
  37. from simple_salesforce import Salesforce
  38. sf = Salesforce(username='myemail@example.com', password='password', security_token='token')
  39. To login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:
  40. .. code-block:: python
  41. from simple_salesforce import Salesforce
  42. sf = Salesforce(password='password', username='myemail@example.com', organizationId='OrgId')
  43. If you'd like to enter a sandbox, simply add ``domain='test'`` to your ``Salesforce()`` call.
  44. For example:
  45. .. code-block:: python
  46. from simple_salesforce import Salesforce
  47. sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', domain='test')
  48. 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.
  49. If you'd like to keep track where your API calls are coming from, simply add ``client_id='My App'`` to your ``Salesforce()`` call.
  50. .. code-block:: python
  51. from simple_salesforce import Salesforce
  52. sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', client_id='My App', domain='test')
  53. If you view the API calls in your Salesforce instance by Client Id it will be prefixed with ``RestForce/``, for example ``RestForce/My App``.
  54. When instantiating a `Salesforce` object, it's also possible to include an
  55. instance of `requests.Session`. This is to allow for specialized
  56. session handling not otherwise exposed by simple_salesforce.
  57. For example:
  58. .. code-block:: python
  59. from simple_salesforce import Salesforce
  60. import requests
  61. session = requests.Session()
  62. # manipulate the session instance (optional)
  63. sf = Salesforce(
  64. username='user@example.com', password='password', organizationId='OrgId',
  65. session=session)
  66. Record Management
  67. -----------------
  68. To create a new 'Contact' in Salesforce:
  69. .. code-block:: python
  70. sf.Contact.create({'LastName':'Smith','Email':'example@example.com'})
  71. This will return a dictionary such as ``{u'errors': [], u'id': u'003e0000003GuNXAA0', u'success': True}``
  72. To get a dictionary with all the information regarding that record, use:
  73. .. code-block:: python
  74. contact = sf.Contact.get('003e0000003GuNXAA0')
  75. To get a dictionary with all the information regarding that record, using a **custom** field that was defined as External ID:
  76. .. code-block:: python
  77. contact = sf.Contact.get_by_custom_id('My_Custom_ID__c', '22')
  78. To change that contact's last name from 'Smith' to 'Jones' and add a first name of 'John' use:
  79. .. code-block:: python
  80. sf.Contact.update('003e0000003GuNXAA0',{'LastName': 'Jones', 'FirstName': 'John'})
  81. To delete the contact:
  82. .. code-block:: python
  83. sf.Contact.delete('003e0000003GuNXAA0')
  84. To retrieve a list of Contact records deleted over the past 10 days (datetimes are required to be in UTC):
  85. .. code-block:: python
  86. import pytz
  87. import datetime
  88. end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this!
  89. sf.Contact.deleted(end - datetime.timedelta(days=10), end)
  90. To retrieve a list of Contact records updated over the past 10 days (datetimes are required to be in UTC):
  91. .. code-block:: python
  92. import pytz
  93. import datetime
  94. end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this
  95. sf.Contact.updated(end - datetime.timedelta(days=10), end)
  96. Note that Update, Delete and Upsert actions return the associated `Salesforce HTTP Status Code`_
  97. Use the same format to create any record, including 'Account', 'Opportunity', and 'Lead'.
  98. Make sure to have all the required fields for any entry. The `Salesforce API`_ has all objects found under 'Reference -> Standard Objects' and the required fields can be found there.
  99. .. _Salesforce HTTP Status Code: http://www.salesforce.com/us/developer/docs/api_rest/Content/errorcodes.htm
  100. .. _Salesforce API: https://www.salesforce.com/developer/docs/api/
  101. Queries
  102. -------
  103. It's also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).
  104. SOQL queries are done via:
  105. .. code-block:: python
  106. sf.query("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
  107. If, due to an especially large result, Salesforce adds a ``nextRecordsUrl`` to 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)
  108. .. code-block:: python
  109. sf.query_more("01gD0000002HU6KIAW-2000")
  110. sf.query_more("/services/data/v26.0/query/01gD0000002HU6KIAW-2000", True)
  111. As a convenience, to retrieve all of the results in a single local method call use
  112. .. code-block:: python
  113. sf.query_all("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
  114. SOSL queries are done via:
  115. .. code-block:: python
  116. sf.search("FIND {Jones}")
  117. There is also 'Quick Search', which inserts your query inside the {} in the SOSL syntax. Be careful, there is no escaping!
  118. .. code-block:: python
  119. sf.quick_search("Jones")
  120. Search and Quick Search return ``None`` if there are no records, otherwise they return a dictionary of search results.
  121. More details about syntax is available on the `Salesforce Query Language Documentation Developer Website`_
  122. .. _Salesforce Query Language Documentation Developer Website: http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm
  123. Other Options
  124. -------------
  125. To insert or update (upsert) a record using an external ID, use:
  126. .. code-block:: python
  127. sf.Contact.upsert('customExtIdField__c/11999',{'LastName': 'Smith','Email': 'smith@example.com'})
  128. To retrieve basic metadata use:
  129. .. code-block:: python
  130. sf.Contact.metadata()
  131. To retrieve a description of the object, use:
  132. .. code-block:: python
  133. sf.Contact.describe()
  134. To retrieve a description of the record layout of an object by its record layout unique id, use:
  135. .. code-block:: python
  136. sf.Contact.describe_layout('39wmxcw9r23r492')
  137. To retrieve a list of top level description of instance metadata, user:
  138. .. code-block:: python
  139. sf.describe()
  140. for x in sf.describe()["sobjects"]:
  141. print x["label"]
  142. Using Bulk
  143. ----------
  144. You can use this library to access Bulk API functions.
  145. Create new records:
  146. .. code-block:: python
  147. data = [{'LastName':'Smith','Email':'example@example.com'}, {'LastName':'Jones','Email':'test@test.com'}]
  148. sf.bulk.Contact.insert(data)
  149. Update existing records:
  150. .. code-block:: python
  151. data = [{'Id': '0000000000AAAAA', 'Email': 'examplenew@example.com'}, {'Id': '0000000000BBBBB', 'Email': 'testnew@test.com'}]
  152. sf.bulk.Contact.update(data)
  153. Upsert records:
  154. .. code-block:: python
  155. data = [{'Id': '0000000000AAAAA', 'Email': 'examplenew2@example.com'}, {'Id': '', 'Email': 'foo@foo.com'}]
  156. sf.bulk.Contact.upsert(data, 'Id')
  157. Query records:
  158. .. code-block:: python
  159. query = 'SELECT Id, Name FROM Account LIMIT 10'
  160. sf.bulk.Account.query(query)
  161. Delete records (soft deletion):
  162. .. code-block:: python
  163. data = [{'Id': '0000000000AAAAA'}]
  164. sf.bulk.Contact.delete(data)
  165. Hard deletion:
  166. .. code-block:: python
  167. data = [{'Id': '0000000000BBBBB'}]
  168. sf.bulk.Contact.hard_delete(data)
  169. Using Apex
  170. ----------
  171. You can also use this library to call custom Apex methods:
  172. .. code-block:: python
  173. payload = {
  174. "activity": [
  175. {"user": "12345", "action": "update page", "time": "2014-04-21T13:00:15Z"}
  176. ]
  177. }
  178. result = sf.apexecute('User/Activity', method='POST', data=payload)
  179. This would call the endpoint ``https://<instance>.salesforce.com/services/apexrest/User/Activity`` with ``data=`` as
  180. the body content encoded with ``json.dumps``
  181. You can read more about Apex on the `Force.com Apex Code Developer's Guide`_
  182. .. _Force.com Apex Code Developer's Guide: http://www.salesforce.com/us/developer/docs/apexcode
  183. Additional Features
  184. -------------------
  185. There are a few helper classes that are used internally and available to you.
  186. Included in them are ``SalesforceLogin``, which takes in a username, password, security token, optional version and optional domain and returns a tuple of ``(session_id, sf_instance)`` where `session_id` is the session ID to use for authentication to Salesforce and ``sf_instance`` is the domain of the instance of Salesforce to use for the session.
  187. For example, to use SalesforceLogin for a sandbox account you'd use:
  188. .. code-block:: python
  189. from simple_salesforce import SalesforceLogin
  190. session_id, instance = SalesforceLogin(
  191. username='myemail@example.com.sandbox',
  192. password='password',
  193. security_token='token',
  194. domain='test')
  195. Simply leave off the final domain if you do not wish to use a sandbox.
  196. Also exposed is the ``SFType`` class, which is used internally by the ``__getattr__()`` method in the ``Salesforce()`` class and represents a specific SObject type. ``SFType`` requires ``object_name`` (i.e. ``Contact``), ``session_id`` (an authentication ID), ``sf_instance`` (hostname of your Salesforce instance), and an optional ``sf_version``
  197. To add a Contact using the default version of the API you'd use:
  198. .. code-block:: python
  199. from simple_salesforce import SFType
  200. contact = SFType('Contact','sesssionid','na1.salesforce.com')
  201. contact.create({'LastName':'Smith','Email':'example@example.com'})
  202. To use a proxy server between your client and the SalesForce endpoint, use the proxies argument when creating SalesForce object.
  203. The proxy argument is the same as what requests uses, a map of scheme to proxy URL:
  204. .. code-block:: python
  205. proxies = {
  206. "http": "http://10.10.1.10:3128",
  207. "https": "http://10.10.1.10:1080",
  208. }
  209. SalesForce(instance='na1.salesforce.com', session_id='', proxies=proxies)
  210. All results are returned as JSON converted OrderedDict to preserve order of keys from REST responses.
  211. Authors & License
  212. -----------------
  213. This package is released under an open source Apache 2.0 license. Simple-Salesforce was originally written by `Nick Catalano`_ but most newer features and bugfixes come from `community contributors`_. Pull requests submitted to the `GitHub Repo`_ are highly encouraged!
  214. Authentication mechanisms were adapted from Dave Wingate's `RestForce`_ and licensed under a MIT license
  215. The latest build status can be found at `Travis CI`_
  216. .. _Nick Catalano: https://github.com/nickcatal
  217. .. _community contributors: https://github.com/simple-salesforce/simple-salesforce/graphs/contributors
  218. .. _RestForce: http://pypi.python.org/pypi/RestForce/
  219. .. _GitHub Repo: https://github.com/simple-salesforce/simple-salesforce
  220. .. _Travis CI: https://travis-ci.org/simple-salesforce/simple-salesforce
  221. Keywords: python salesforce salesforce.com
  222. Platform: UNKNOWN
  223. Classifier: Development Status :: 4 - Beta
  224. Classifier: License :: OSI Approved :: Apache Software License
  225. Classifier: Intended Audience :: Developers
  226. Classifier: Intended Audience :: System Administrators
  227. Classifier: Operating System :: OS Independent
  228. Classifier: Topic :: Internet :: WWW/HTTP
  229. Classifier: Programming Language :: Python :: 2.6
  230. Classifier: Programming Language :: Python :: 2.7
  231. Classifier: Programming Language :: Python :: 3.3
  232. Classifier: Programming Language :: Python :: 3.4
  233. Classifier: Programming Language :: Python :: 3.5
  234. Classifier: Programming Language :: Python :: 3.6
  235. Classifier: Programming Language :: Python :: Implementation :: PyPy