Metadata-Version: 1.0
Name: beatbox
Version: 19.0
Summary: A Python library for querying/updating Saleforce.com data via SOAP API
Home-page: http://code.google.com/p/salesforce-beatbox/
Author: Simon Fell et al
Author-email: plonesf@googlegroups.com
License: GNU GENERAL PUBLIC LICENSE Version 2
Description: Introduction
        ============
        
        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
        Salesforce.com Partner Web Services API.
        
        .. _`beatbox module`: http://www.pocketsoap.com/beatbox/
        
        This module contains 2 versions of the Salesforce.com client:
        
        XMLClient
        The original beatbox version of the client which returns xmltramp objects.
        PythonClient
        Marshalls the returned objects into proper Python data types. e.g. integer
        fields return integers.
        
        
        Compatibility
        =============
        
        Beatbox supports versions 16.0 through 19.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
        * describeDataCategoryGroups
        * describeDataCategoryGroupStructures
        
        Beatbox has been tested with Python 2.4 and Python 2.6.
        
        
        Basic Usage Examples
        ====================
        
        Instantiate a Python Salesforce.com client:
        >>> svc = beatbox.PythonClient()
        >>> svc.login('username', 'passwordTOKEN')
        
        (Note that interacting with Salesforce.com 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
        '0037000000eRf6vAAC'
        
        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']
        '00Q7000000RVyiHEAT'
        
        
        More Examples
        =============
        
        The examples folder contains the examples for the original beatbox. For
        examples on how to use the PythonClient see
        src/beatbox/tests/test_pythonClient.py.
        
        Some of these other products that have been built on top of beatbox can also
        provide example of use:
        
        * `Salesforce Base Connector`_
        * `Salesforce PFG Adapter`_
        * `Salesforce Auth Plugin`_
        * `RSVP for Salesforce`_
        
        .. _`Salesforce Base Connector`: http://plone.org/products/salesforcebaseconnector
        .. _`Salesforce PFG Adapter`: http://plone.org/products/salesforcepfgadapter
        .. _`Salesforce Auth Plugin`: http://plone.org/products/salesforceauthplugin
        .. _`RSVP for Salesforce`: http://plone.org/products/collective.salesforce.rsvp
        
        
        Alternatives
        ============
        
        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).
        
        .. _`Python Salesforce Toolkit`: http://code.google.com/p/salesforce-python-toolkit/
        .. _`suds`: https://fedorahosted.org/suds/
        
        Ron Hess from Salesforce.com has adapted beatbox for use with Google App
        Engine.  See http://code.google.com/p/force-app-engine/
        
        
        Running Tests
        =============
        
        First, we need to add some custom fields to the Contacts object in your Salesforce instance:
        
        * Login to your Salesforce.com 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/test_beatbox.py
        python src/beatbox/tests/test_pythonClient.py
        
        
        Changelog
        =========
        
        19.0 (2010-08-23)
        -----------------
        
        * Update marshalling of describeGlobal and describeSObjects responses to
        include new properties now returned by the API.  For backwards
        compatibility, we set the types property of the describeGlobal response
        to a list of the names of all types (which Salesforce now returns in
        separate DescribeGlobalSObjectResult objects).
        [davisagli]
        
        * Update to use version 19.0 of the Salesforce.com partner WSDL by default.
        Also, use the new login.salesforce.com login endpoint by default.
        [davisagli]
        
        16.1 (2010-03-11)
        -----------------
        
        * Catch and retry on exceptions from the socket library, in addition to ones
        from httplib.  This fixes a regression introduced in version 16.0.
        [davisagli]
        
        
        16.0 (2009-11-12)
        -----------------
        
        * Don't strip newlines when marshalling the values of textarea fields.
        [davisagli]
        
        * Make sure to add a field to fieldsToNull if its Python value is None.
        [rhettg, davisagli]
        
        * Fix issue where numbers of type long weren't converted to a string.
        [spleeman, davisagli]
        
        * Only catch HTTP exceptions when retrying a connection.
        [spleeman, davisagli]
        
        
        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 Salesforce.com.
        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 Salesforce.com 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)
        -----------------
        
        * Access 'created' instead of 'isCreated' in the upsert result. This closes
        http://code.google.com/p/salesforce-beatbox/issues/detail?id=4
        [davisagli]
        
        0.10 (2009-05-06)
        -----------------
        
        * Added optional serverUrl parameter when creating a Client.
        [davisagli]
        
        pre 0.9.1.1
        -----------
        
        * ancient history
Keywords: python salesforce salesforce.com
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
