Merge pull request #67 from cstarner/master

Added Change Data Capture Support

Author: ej2

README.rst

@@ -245,6 +245,38 @@ Review results for batch operation:
         for error in fault.Error:
             print "Error " + error.Message 
 
+Change Data Capture
+-----------------------
+Change Data Capture returns a list of objects that have changed since a given time (see `Change data capture`_ for more
+details):
+
+::
+
+   from quickbooks.cdc import change_data_capture
+   from quickbooks.objects import Invoice
+
+   cdc_response = change_data_capture([Invoice], "2017-01-01T00:00:00", qb=client)
+   for invoice in cdc_response.Invoice:
+      # Do something with the invoice
+
+Querying muliple entity types at the same time:
+
+::
+
+   from quickbooks.objects import Invoice, Customer
+
+   cdc_response = change_data_capture([Invoice, Customer], "2017-01-01T00:00:00", qb=client)
+
+
+If you use a ``datetime`` object for the timestamp, it is automatically converted to a string:
+
+::
+
+   from datetime import datetime
+
+   cdc_response = change_data_capture([Invoice, Customer], datetime(2017, 1, 1, 0, 0, 0), qb=client)
+
+
 Attachments
 ----------------
 See `Attachable documentation`_ for list of valid file types, file size limits and other restrictions.
@@ -279,6 +311,8 @@ Attaching a file to customer:
      attachment.ContentType = 'application/pdf'
      attachment.save(qb=client)
 
+
+
 Working with JSON data
 ----------------
 All objects include ``to_json`` and ``from_json`` methods.
@@ -330,6 +364,8 @@ on Python 2.
 .. _Minor versions: https://developer.intuit.com/docs/0100_quickbooks_online/0200_dev_guides/accounting/minor_versions
 .. _Attachable documentation: https://developer.intuit.com/docs/api/accounting/Attachable
 .. _Integration tests folder: https://github.com/sidecars/python-quickbooks/tree/master/tests/integration
+.. _Change data capture: https://developer.intuit.com/docs/api/accounting/changedatacapture
+
 
 .. |Build Status| image:: https://travis-ci.org/sidecars/python-quickbooks.svg?branch=master
    :target: https://travis-ci.org/sidecars/python-quickbooks

quickbooks/cdc.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+from .client import QuickBooks
+from .objects.changedatacapture import QueryResponse, CDCResponse
+from .helpers import qb_datetime_format
+
+
+def change_data_capture(qbo_class_list, timestamp, qb=None):
+	if qb is None:
+		qb = QuickBooks()
+
+	cdc_class_dict = dict((cls.qbo_object_name, cls) for cls in qbo_class_list)
+
+	cdc_class_names = list(cdc_class_dict.keys())
+	entity_list_string = ','.join(cdc_class_names)
+
+	if isinstance(timestamp, datetime):
+		timestamp_string = qb_datetime_format(timestamp)
+	else:
+		timestamp_string = timestamp
+
+	resp = qb.change_data_capture(entity_list_string, timestamp_string)
+
+	cdc_response_dict = resp.pop('CDCResponse')
+	cdc_response = CDCResponse.from_json(resp)
+
+	query_response_list = cdc_response_dict[0]['QueryResponse']
+	for query_response_dict in query_response_list:
+		qb_object_name = [x for x in query_response_dict if x in cdc_class_names][0]
+		qb_object_list = query_response_dict.pop(qb_object_name)
+		qb_object_cls = cdc_class_dict[qb_object_name]
+
+		query_response = QueryResponse.from_json(query_response_dict)
+		query_response._object_list = [qb_object_cls.from_json(obj) for obj in qb_object_list]
+
+		setattr(cdc_response, qb_object_name, query_response)
+
+	return cdc_response

quickbooks/client.py

@@ -203,7 +203,6 @@ def get_access_tokens(self, oauth_verifier):
 
         self.access_token = session.access_token
         self.access_token_secret = session.access_token_secret
-
         return session
 
     def disconnect_account(self):
@@ -215,6 +214,14 @@ def disconnect_account(self):
         result = self.make_request("GET", url)
         return result
 
+    def change_data_capture(self, entity_string, changed_since):
+        url = self.api_url + "/company/{0}/cdc".format(self.company_id)
+
+        params = {"entities": entity_string, "changedSince": changed_since}
+
+        result = self.make_request("GET", url, params=params)
+        return result
+
     def reconnect_account(self):
         """
         Reconnect current account by refreshing OAuth access tokens

quickbooks/mixins.py

@@ -223,3 +223,36 @@ def download_pdf(self, qb=None):
             raise QuickbooksException(
                 "Cannot download {0} when no Id is assigned or if no quickbooks client is passed in".format(
                     self.qbo_object_name))
+
+
+class ObjectListMixin(object):
+    qbo_object_name = ""
+    _object_list = []
+
+    def __iter__(self):
+        return self._object_list.__iter__()
+
+    def __len__(self):
+        return self._object_list.__len__()
+
+    def __contains__(self, item):
+        return self._object_list.__contains__(item)
+
+    def __getitem__(self, key):
+        # if key is of invalid type or value, the list values will raise the error
+        return self._object_list.__getitem__(key)
+
+    def __setitem__(self, key, value):
+        self._object_list.__setitem__(key, value)
+
+    def __delitem__(self, key):
+        self._object_list.__delitem__(key)
+
+    def __reversed__(self):
+        return self._object_list.__reversed__()
+
+    def append(self, value):
+        self._object_list.append(value)
+
+    def pop(self, *args, **kwargs):
+        return self._object_list.pop(*args, **kwargs)

quickbooks/objects/changedatacapture.py

@@ -0,0 +1,15 @@
+from ..mixins import FromJsonMixin, ObjectListMixin
+
+
+class CDCResponse(FromJsonMixin):
+	qbo_object_name = "CDCResponse"
+
+	def __init__(self):
+		super(CDCResponse, self).__init__()
+
+
+class QueryResponse(FromJsonMixin, ObjectListMixin):
+	qbo_object_name = "QueryResponse"
+
+	def __init__(self):
+		super(QueryResponse, self).__init__()

requirements.txt

@@ -0,0 +1,4 @@
+rauth>=0.7.1
+requests>=2.7.0
+simplejson>=2.2.0
+six>=1.4.0

tests/integration/test_purchaseorder.py

@@ -46,7 +46,7 @@ def test_create(self):
         purchaseorder.APAccountRef = account.to_ref()
         purchaseorder.TotalAmt = 100
 
-        print purchaseorder.to_json()
+        #print purchaseorder.to_json()
         purchaseorder.save(qb=self.qb_client)
 
         query_purchaseorder = PurchaseOrder.get(purchaseorder.Id, qb=self.qb_client)

tests/unit/test_batch.py

@@ -1,5 +1,8 @@
 import unittest
-from mock import patch
+try:
+    from mock import patch
+except ImportError:
+    from unittest.mock import patch
 from quickbooks import batch, client
 from quickbooks.objects.customer import Customer
 from quickbooks.exceptions import QuickbooksException

tests/unit/test_cdc.py

@@ -0,0 +1,90 @@
+import unittest
+try:
+	from mock import patch
+except ImportError:
+	from unittest.mock import patch
+from quickbooks.cdc import change_data_capture
+from quickbooks.objects import Invoice, Customer
+from quickbooks import QuickBooks
+from datetime import datetime
+
+class ChangeDataCaptureTest(unittest.TestCase):
+
+	def setUp(self):
+		self.qb_client = QuickBooks(
+			sandbox=True,
+			consumer_key="update_consumer_key",
+			consumer_secret="update_consumer_secret",
+			access_token="update_access_token",
+			access_token_secret="update_access_token_secret",
+			company_id="update_company_id",
+			callback_url="update_callback_url"
+		)
+
+		self.cdc_json_response = {
+			"CDCResponse": [
+				{
+					"QueryResponse": [
+						{
+							"Customer": [
+								{
+									"Id": 1,
+									"DisplayName": "TestCustomer",
+									"Job": False,
+									"Balance": 0
+								}
+							],
+							"startPosition": 1,
+							"maxResults": 1
+						},
+						{
+							"Invoice": [
+								{
+									"DocNumber": "12344",
+									"TxnDate": "2017-01-01",
+									"Line": [
+										{
+											"Id": 1
+										},
+										{
+											"Id": 2
+										}
+									]
+								},
+								{
+									"DocNumber": "12345",
+									"TxnDate": "2017-01-01",
+									"Line": [
+										{
+											"Id": 1
+										},
+										{
+											"Id": 2
+										}
+									]
+								},
+							],
+							"startPosition": 1,
+							"maxResults": 2
+						}
+					]
+				}
+			],
+			"time": "2016-01-01T00:00:00"
+		}
+
+
+	@patch('quickbooks.client.QuickBooks.make_request')
+	def test_change_data_capture(self, make_request):
+		make_request.return_value = self.cdc_json_response.copy()
+		cdc_response = change_data_capture([Invoice, Customer], "2017-01-01T00:00:00")
+		self.assertEquals(1, len(cdc_response.Customer))
+		self.assertEquals(2, len(cdc_response.Invoice))
+
+
+	@patch('quickbooks.client.QuickBooks.make_request')
+	def test_change_data_capture_with_timestamp(self, make_request):
+		make_request.return_value = self.cdc_json_response.copy()
+		cdc_response_with_datetime = change_data_capture([Invoice, Customer], datetime(2017, 1, 1, 0, 0, 0))
+		self.assertEquals(1, len(cdc_response_with_datetime.Customer))
+		self.assertEquals(2, len(cdc_response_with_datetime.Invoice))

tests/unit/test_client.py

@@ -1,6 +1,9 @@
 import unittest
 
-from mock import patch
+try:
+    from mock import patch
+except ImportError:
+    from unittest.mock import patch
 
 from quickbooks.exceptions import QuickbooksException, SevereException
 from quickbooks import client