Skip to main content

A Python library for querying/updating data via SOAP API

Project description


This is a distutils-packaged and updated version of the beatbox module by Simon Fell, which is a Python implementation of a client for the Partner Web Services API.

This module contains 2 versions of the client:


The original beatbox version of the client which returns xmltramp objects.


Marshalls the returned objects into proper Python data types. e.g. integer fields return integers.


Beatbox supports version 16.0 of the Salesforce Partner Web Services API. However, the following API calls have not been implemented at this time:

  • convertLead

  • emptyRecycleBin

  • invalidateSessions

  • logout

  • merge

  • process

  • queryAll

  • undelete

  • describeSObject

  • sendEmail

Beatbox has been tested with Python 2.4 and Python 2.6.

Basic Usage Examples

Instantiate a Python client:
>>> svc = beatbox.PythonClient()
>>> svc.login('username', 'passwordTOKEN')

(Note that interacting with via the API requires the use of a ‘security token’ which must be appended to the password.)

Query for contacts with last name ‘Doe’:
>>> res = svc.query("SELECT Id, FirstName, LastName FROM Contact WHERE LastName='Doe'")
>>> res[0]
{'LastName': 'Doe', 'type': 'Contact', 'Id': '0037000000eRf6vAAC', 'FirstName': 'John'}
>>> res[0].Id
Add a new Lead:
>>> contact = {'type': 'Lead', 'LastName': 'Glick', 'FirstName': 'David', 'Company': 'Individual'}
>>> res = svc.create(contact)
Get the ID of the newly created Lead:
>>> res[0]['id']

More Examples

The examples folder contains the examples for the original beatbox. For examples on how to use the PythonClient see src/beatbox/tests/

Some of these other products that have been built on top of beatbox can also provide example of use:


David Lanstein has created a Python Salesforce Toolkit that is based on the suds SOAP library. Based on limited tests it appears to be somewhat slower than beatbox for operations that return a lot of data; however, it may be a better option if you want to be able to automatically generate a service proxy for a new WSDL (such as for the Enterprise web services API).

Ron Hess from has adapted beatbox for use with Google App Engine. See

Running Tests

First, we need to add some custom fields to the Contacts object in your Salesforce instance:

  • Login to your instance

  • Browse to Setup –> Customize –> Contacts –> Fields –> “New” button

  • Add a Picklist (multi-select) labeled “Favorite Fruit”, then add
    • Apple

    • Orange

    • Pear

  • Leave default of 3 lines and field name should default to “Favorite_Fruit”

  • Add a Number labeled “Favorite Integer”, with 18 places, 0 decimal places

  • Add a Number labeled “Favorite Float”, with 13 places, 5 decimal places

Create a sfconfig file in your python path with the following format:

USERNAME='your salesforce username'
PASSWORD='your salesforce passwordTOKEN'

where TOKEN is your Salesforce API login token.

Add ‘./src’ to your PYTHONPATH

Run the tests:

python src/beatbox/tests/
python src/beatbox/tests/


16.0b1 (2009-09-08)

  • Log beatbox calls at the debug level. [davisagli]

  • Fixed a string exception for compatibility with Python 2.6. [davisagli]

  • Added support for SOSL searches via the search method. Thanks to Alex Tokar of Web Collective. [davisagli]

  • Added an optional cache for the sObject type descriptions needed for marshalling query results into Python objects. This can avoid an extra describeSObjects API call for each query, but means that the information could become stale if the type metadata is modified in The cache is off by default. Turn it on by passing cacheTypeDescriptions=True when instantiating a Python client. The cache may be reset by calling the flushTypeDescriptionsCache method of the Python client. [davisagli]

  • Support a full SOQL statement as a parameter to the query method of the Python client. The old 3-part method signature (fields, sObjectType, conditionalExpression) should continue to work. [davisagli]

  • In the Python client, support relationship queries and other queries that may return multiple types of objects. Object type descriptions (required for marshalling field values into the correct Python type) are cached for the duration of the query after the first time they are used. Thanks to Melnychuk Taras of Quintagroup. [davisagli]

  • In the Python client, queries now return a list-like QueryRecordSet holding a sequence of dict-like QueryRecord objects, instead of a dict containing a list of dicts. This allows for more Pythonic access such as results[0].Id instead of results[‘results’][0][‘Id’]. The old syntax should still work. Thanks to Melnychuk Taras of Quintagroup. [davisagli]

  • Update to use version 16.0 of the partner WSDL. [davisagli]

0.12 (2009-05-13)

  • Use the default serverUrl value if the passed value evaluates to boolean False. [davisagli]

0.11 (2009-05-13)

0.10 (2009-05-06)

  • Added optional serverUrl parameter when creating a Client. [davisagli]


  • ancient history

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beatbox-16.0b1.tar.gz (36.4 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page