Merge pull request #74 from timotheus/enhanced-response

Enhanced response work

.gitignore

@@ -1,3 +1,4 @@
+timebay.yaml
 build/
 dist/
 tkebay.yaml

Changes

@@ -1,5 +1,16 @@
 Changes for ebaysdk
 
+2.0.0
+- WARNING!! This release breaks some backward compatibility
+  Read https://github.com/timotheus/ebaysdk-python/wiki/Migrating-from-v1-to-v2
+- imports: Modified package structure
+- execute(): Modified return value
+- Switched to lxml.etree
+- Added a new response class
+  response.reply, response.dom(), response.dict(), response.json()
+- Added ebaysdk exception classes
+- Modified utils.py (dict2xml, xml2dict)
+
 1.0.3
 - rework unicode fix
 - fix logging handler

README.rst

@@ -5,14 +5,33 @@ This SDK is a programmatic interface into the eBay APIs. It simplifies developme
 
 Quick Example::
 
+    import datetime
+    from lxml.etree import _Element
     from ebaysdk.finding import Connection
+
     try:
         api = Connection(appid='YOUR_APPID_HERE')
-        api.execute('findItemsAdvanced', {'keywords': 'shoes'})        
+        response = api.execute('findItemsAdvanced', {'keywords': 'legos'})        
+
+        assert(response.reply.ack == 'Success')  
+        assert(type(response.reply.timestamp) == datetime.datetime)
+        assert(type(response.reply.searchResult.item) == list)
+  
+        item = response.reply.searchResult.item[0]
+        assert(type(item.listingInfo.endTime) == datetime.datetime)
+        assert(type(response.dict()) == dict)
+        assert(type(response.dom() == _Element)
 
-        print api.response_dict()
     except ConnectionError as e:
-        raise e
+        print(e)
+        print(e.response.dict())
+
+
+Migrating from v1 to v2
+-----------------------
+
+For a complete guide on migrating from ebaysdk v1 to v2 and see an overview of the additional features in v2 please read the `v1 to v2 guide`_
+
 
 Getting Started
 ---------------
@@ -63,5 +82,5 @@ License
 .. _Parallel Class: https://github.com/timotheus/ebaysdk-python/wiki/Parallel-Class
 .. _eBay Developer Forums: https://www.x.com/developers/ebay/forums
 .. _Github issue tracking: https://github.com/timotheus/ebaysdk-python/issues
-
+.. _v1 to v2 guide: https://github.com/timotheus/ebaysdk-python/wiki/Migrating-from-v1-to-v2 
 

docs/index.rst

@@ -1,29 +1,94 @@
-Welcome to the ebaysdk for Python
-=================================
+Welcome to the python ebaysdk
+=============================
 
-Welcome to the eBay SDK for Python. This SDK cuts development time and simplifies tasks like error handling and enables you to make Finding, Shopping, Merchandising, and Trading API calls. In Addition, the SDK comes with RSS and HTML back-end libraries.
+This SDK is a programmatic interface into the eBay APIs. It simplifies development and cuts development time by standardizing calls, response processing, error handling, and debugging across the Finding, Shopping, Merchandising & Trading APIs. 
 
-In order to use eBay aspects of this utility you must first register with eBay to get your `eBay Developer Site`_ (see the ebay.yaml for a way to easily tie eBay credentials to the SDK) Finding Services.
+Quick Start::
+    import datetime
+    from lxml.etree import _Element
+    from ebaysdk.finding import Connection
 
-Example::
+    try:
+        api = Connection(appid='YOUR_APPID_HERE')
+        response = api.execute('findItemsAdvanced', {'keywords': 'legos'})        
 
-    from ebaysdk import getNodeText
-    from ebaysdk.finding import Connection as finding
+        assert(response.reply.ack == 'Success')  
+        assert(type(response.reply.timestamp) == datetime.datetime)
+        assert(type(response.reply.searchResult.item) == list)
+  
+        item = response.reply.searchResult.item[0]
+        assert(type(item.listingInfo.endTime) == datetime.datetime)
+        assert(type(response.dict()) == dict)
+        assert(type(response.dom() == _Element)
 
-    f = finding()
-    f.execute('findItemsAdvanced', {'keywords': 'shoes'})        
+    except ConnectionError as e:
+        raise e
 
-    dom    = f.response_dom()
-    mydict = f.response_dict()
 
-    # shortcut to response data
-    print f.v('itemSearchURL')
+Migrating from v1 to v2
+-----------------------
 
-    # process the response via DOM
-    items = dom.getElementsByTagName('item')
+After lots of planning and beating my head against the wall, version 2 of this SDK has come to contain a few changes that break backward compatibility. These changes were necessary to optimize this project and help keep it moving forward. Below I’ll highlight the changes and point out code changes that you may need to make.
 
-    for item in items:
-      print getNodeText(item.getElementsByTagName('title')[0])
+Changes
 
+* Import: Modified package structure
+* execute(): Modified return value
+* Switched to lxml.etree
+* Added a new response class (response.reply, response.dom(), response.dict(), response.json())
+* Added ebaysdk exception classes
+* Modified utils.py (dict2xml, xml2dict)
+
+Please read the full doc on `Migrating from ebaysdk v1 to v2`_
+
+Getting Started
+---------------
+
+SDK Classes
+
+* `Trading API Class`_ - secure, authenticated access to private eBay data.
+* `Finding API Class`_ - access eBay's next generation search capabilities.
+* `Shopping API Class`_ - performance-optimized, lightweight APIs for accessing public eBay data.
+* `Merchandising API Class`_ - find items and products on eBay that provide good value or are otherwise popular with eBay buyers.
+* `HTML Class`_ - generic back-end class the enbles and standardized way to make API calls.
+* `Parallel Class`_ - SDK support for concurrent API calls.
+
+SDK Configuration
+
+* `YAML Configuration`_ 
+* `Understanding eBay Credentials`_
+
+
+Support
+-------
+
+For developer support regarding the SDK code base please use this project's `Github issue tracking`_.
+
+For developer support regarding the eBay APIs please use the `eBay Developer Forums`_.
+
+Install
+-------
+
+Installation instructions for *nix and windows can be found in the `INSTALL file`_.
+
+License
+-------
+
+`COMMON DEVELOPMENT AND DISTRIBUTION LICENSE`_ Version 1.0 (CDDL-1.0)
+
+
+.. _INSTALL file: https://github.com/timotheus/ebaysdk-python/blob/master/INSTALL
+.. _COMMON DEVELOPMENT AND DISTRIBUTION LICENSE: http://opensource.org/licenses/CDDL-1.0
+.. _Understanding eBay Credentials: https://github.com/timotheus/ebaysdk-python/wiki/eBay-Credentials
 .. _eBay Developer Site: http://developer.ebay.com/
+.. _YAML Configuration: https://github.com/timotheus/ebaysdk-python/wiki/YAML-Configuration
+.. _Trading API Class: https://github.com/timotheus/ebaysdk-python/wiki/Trading-API-Class
+.. _Finding API Class: https://github.com/timotheus/ebaysdk-python/wiki/Finding-API-Class
+.. _Shopping API Class: https://github.com/timotheus/ebaysdk-python/wiki/Shopping-API-Class
+.. _Merchandising API Class: https://github.com/timotheus/ebaysdk-python/wiki/Merchandising-API-Class
+.. _HTML Class: https://github.com/timotheus/ebaysdk-python/wiki/HTML-Class
+.. _Parallel Class: https://github.com/timotheus/ebaysdk-python/wiki/Parallel-Class
+.. _eBay Developer Forums: https://www.x.com/developers/ebay/forums
+.. _Github issue tracking: https://github.com/timotheus/ebaysdk-python/issues
+.. _Migrating from ebaysdk v1 to v2: https://github.com/timotheus/ebaysdk-python/wiki/Migrating-from-v1-to-v2
 

ebaysdk/__init__.py

@@ -9,7 +9,7 @@
 import platform
 import logging
 
-__version__ = '1.0.3'
+__version__ = '2.0.0'
 Version = __version__  # for backware compatibility
 
 try:

ebaysdk/config.py

@@ -10,6 +10,7 @@
 import yaml
 
 from ebaysdk import log
+from ebaysdk.exception import ConnectionError
 
 class Config(object):
     """Config Class for all APIs connections
@@ -67,6 +68,9 @@ def _populate_yaml_defaults(self):
 
                 return self
 
+        if self.config_file:
+            raise ConnectionError('config file %s not found' % self.config_file)
+
     def file(self):
         return self.config_file_used