See CHANGES for details on this commit. Lots of cleanup, compatibility with newer PayPal API versions, and cleaning some cruft.

Author: Greg Taylor

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
+*.swp
 .project
 .pydevproject
 .settings

CHANGES

@@ -1,13 +1,31 @@
 Changes introduced with each version.
 
+1.1.0
+-----
+This version addresses compatibility with the newer versions of the PayPal API
+by backing off on pre-query validation. PayPal's API error messages are
+the safest bet, as bad as they can be at times.
+
+Lots of cleanup, commenting, and creature comforts abound. Backwards-incompatible
+changes are prefixed with 'BIC'.
+
+* BIC: Removed the KEY_ERROR setting. Less complexity is better. (gtaylor)
+* Adding lots of logging, which users may attach to for debugging. (gtaylor)
+* Removed RESPONSE_KEYERROR. Wasn't being used. (gtaylor)
+* Removed DEBUG_LEVEL setting. Use Python logging. (gtaylor)
+* Removed some of the error checking on input values, as this
+  limits users to the old API versions. We'll have to rely
+  on PayPal's error messages being informative. (gtaylor)
+* Bumped the default API version protocol to 74.0, up from 53.0. (gtaylor)
+
 1.0.3
 -----
 * Python 2.5 compatibility. (Manik)
 
 1.0.2
 -----
 * Documentation updates. (gtaylor)
-* We now distribute with a copy of the Apache License. (Greg)
+* We now distribute with a copy of the Apache License. (gtaylor)
 
 1.0.1
 -----

paypal/interface.py

@@ -9,10 +9,14 @@
 import socket
 import urllib
 import urllib2
+import logging
+from pprint import pformat
 
 from paypal.settings import PayPalConfig
 from paypal.response import PayPalResponse
 from paypal.exceptions import PayPalError, PayPalAPIResponseError
+
+logger = logging.getLogger('paypal.interface')
 
 class PayPalInterface(object):
     """
@@ -68,11 +72,13 @@ def _call(self, method, **kwargs):
     
         ``kwargs`` will be a hash of
         """
+        # Beware, this is a global setting.
         socket.setdefaulttimeout(self.config.HTTP_TIMEOUT)
-    
+
+        # This dict holds the key/value pairs to pass to the PayPal API.
         url_values = {
             'METHOD': method,
-            'VERSION': self.config.API_VERSION
+            'VERSION': self.config.API_VERSION,
         }
 
         headers = {}
@@ -88,30 +94,27 @@ def _call(self, method, **kwargs):
             url_values['SUBJECT'] = self.config.SUBJECT
         # headers['X-PAYPAL-REQUEST-DATA-FORMAT'] = 'NV'
         # headers['X-PAYPAL-RESPONSE-DATA-FORMAT'] = 'NV'
-        # print(headers)
 
+        # All values passed to PayPal API must be uppercase.
         for key, value in kwargs.iteritems():
             url_values[key.upper()] = value
 
-        # When in DEBUG level 2 or greater, print out the NVP pairs.
-        if self.config.DEBUG_LEVEL >= 2:
-            k = url_values.keys()
-            k.sort()
-            for i in k:
-                print " %-20s : %s" % (i , url_values[i])
+        # This shows all of the key/val pairs we're sending to PayPal.
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug('PayPal NVP Query Key/Vals:\n%s' % pformat(url_values))
 
         url = self._encode_utf8(**url_values)
-
         data = urllib.urlencode(url)
         req = urllib2.Request(self.config.API_ENDPOINT, data, headers)
         response = PayPalResponse(urllib2.urlopen(req).read(), self.config)
 
-        if self.config.DEBUG_LEVEL >= 1:
-            print " %-20s : %s" % ("ENDPOINT", self.config.API_ENDPOINT)
+        logger.debug('PayPal NVP API Endpoint: %s'% self.config.API_ENDPOINT)
 
         if not response.success:
-            if self.config.DEBUG_LEVEL >= 1:
-                print response
+            logger.error('A PayPal API error was encountered.')
+            logger.error('PayPal NVP Query Key/Vals:\n%s' % pformat(url_values))
+            logger.error('PayPal NVP Query Response')
+            logger.error(response)
             raise PayPalAPIResponseError(response)
 
         return response
@@ -284,51 +287,52 @@ def get_transaction_details(self, transactionid):
         del args['self']
         return self._call('GetTransactionDetails', **args)
 
-    def set_express_checkout(self, token='', **kwargs):
-        """Shortcut for the SetExpressCheckout method.
-            JV did not like the original method. found it limiting.
+    def set_express_checkout(self, **kwargs):
+        """Start an Express checkout.
+
+        You'll want to use this in conjunction with
+        :meth:`generate_express_checkout_redirect_url` to create a payment,
+        then figure out where to redirect the user to for them to
+        authorize the payment on PayPal's website.
+
+        Required Keys
+        -------------
+
+        * PAYMENTREQUEST_0_AMT
+        * PAYMENTREQUEST_0_PAYMENTACTION
+        * RETURNURL
+        * CANCELURL
         """
-        kwargs.update(locals())
-        del kwargs['self']
-        self._check_required(('amt',), **kwargs)
         return self._call('SetExpressCheckout', **kwargs)
 
-    def do_express_checkout_payment(self, token, **kwargs):
-        """Shortcut for the DoExpressCheckoutPayment method.
-        
-            Required
-                *TOKEN
-                PAYMENTACTION
-                PAYERID
-                AMT
-                
-            Optional
-                RETURNFMFDETAILS
-                GIFTMESSAGE
-                GIFTRECEIPTENABLE
-                GIFTWRAPNAME
-                GIFTWRAPAMOUNT
-                BUYERMARKETINGEMAIL
-                SURVEYQUESTION
-                SURVEYCHOICESELECTED
-                CURRENCYCODE
-                ITEMAMT
-                SHIPPINGAMT
-                INSURANCEAMT
-                HANDLINGAMT
-                TAXAMT
+    def do_express_checkout_payment(self, **kwargs):
+        """Finishes an Express checkout.
 
-            Optional + USEFUL
-                INVNUM - invoice number
+        :param str token: The token that was returned earlier by
+            :meth:`set_express_checkout`. This identifies the transaction.
+
+        Required
+        --------
+        * TOKEN
+        * PAYMENTACTION
+        * PAYERID
+        * AMT
                 
         """
-        kwargs.update(locals())
-        del kwargs['self']
-        self._check_required(('paymentaction', 'payerid'), **kwargs)
         return self._call('DoExpressCheckoutPayment', **kwargs)
 
     def generate_express_checkout_redirect_url(self, token):
-        """Submit token, get redirect url for client."""
+        """Returns the URL to redirect the user to for the Express checkout.
+
+        Express Checkouts must be verified by the customer by redirecting them
+        to the PayPal website. Use the token returned in the response from
+        :meth:`set_express_checkout` with this function to figure out where
+        to redirect the user to.
+
+        :param str token: The unique token identifying this transaction.
+        :rtype: str
+        :returns: The URL to redirect the user to for approval.
+        """
         url_vars = (self.config.PAYPAL_URL_BASE, token)
         return "%s?cmd=_express-checkout&token=%s" % url_vars
 

paypal/response.py

@@ -5,9 +5,13 @@
 try:
     from urlparse import parse_qs
 except ImportError:
+    # For Python 2.5 compatibility.
     from cgi import parse_qs
 
-import paypal.exceptions 
+import logging
+from pprint import pformat
+
+logger = logging.getLogger('paypal.response')
 
 class PayPalResponse(object):
     """
@@ -20,39 +24,59 @@ class PayPalResponse(object):
     def __init__(self, query_string, config):
         """
         query_string is the response from the API, in NVP format. This is
-        parseable by urlparse.parse_qs(), which sticks it into the self.raw
-        dict for retrieval by the user.
+        parseable by urlparse.parse_qs(), which sticks it into the
+        :attr:`raw` dict for retrieval by the user.
+
+        :param str query_string: The raw response from the API server.
+        :param PayPalConfig config: The config object that was used to send
+            the query that caused this response.
         """
         # A dict of NVP values. Don't access this directly, use
         # PayPalResponse.attribname instead. See self.__getattr__().
         self.raw = parse_qs(query_string)
         self.config = config
+        logger.debug("PayPal NVP API Response:\n%s" % self.__str__())
 
     def __str__(self):
-        return str(self.raw)
+        """
+        Returns a string representation of the PayPalResponse object, in
+        'pretty-print' format.
+
+        :rtype: str
+        :returns: A 'pretty' string representation of the response dict.
+        """
+        return pformat(self.raw)
 
     def __getattr__(self, key):
         """
         Handles the retrieval of attributes that don't exist on the object
-        already. This is used to get API response values.
+        already. This is used to get API response values. Handles some
+        convenience stuff like discarding case and checking the cgi/urlparsed
+        response value dict (self.raw).
+
+        :param str key: The response attribute to get a value for.
+        :rtype: str
+        :returns: The requested value from the API server's response.
         """
         # PayPal response names are always uppercase.
         key = key.upper()
         try:
             value = self.raw[key]
             if len(value) == 1:
+                # TODO: Figure out why we need this.
                 return value[0]
             return value
         except KeyError:
-            if self.config.KEY_ERROR:
-                raise AttributeError(self)
-            else:
-                return None
+            # The requested value wasn't returned in the response.
+            raise AttributeError(self)
 
     def success(self):
         """
-        Checks for the presence of errors in the response. Returns True if
-        all is well, False otherwise.
+        Checks for the presence of errors in the response. Returns ``True`` if
+        all is well, ``False`` otherwise.
+
+        :rtype: bool
+        :returns ``True`` if PayPal says our query was successful.
         """
         return self.ack.upper() in (self.config.ACK_SUCCESS, 
                                     self.config.ACK_SUCCESS_WITH_WARNING)

paypal/settings.py

@@ -4,9 +4,13 @@
 Most of this is transparent to the end developer, as the PayPalConfig object
 is instantiated by the PayPalInterface object.
 """
+import logging
+from pprint import pformat
 
 from paypal.exceptions import PayPalConfigError, PayPalError
 
+logger = logging.getLogger('paypal.settings')
+
 class PayPalConfig(object):
     """
     The PayPalConfig object is used to allow the developer to perform API
@@ -36,7 +40,8 @@ class PayPalConfig(object):
         'production' : 'https://www.paypal.com/webscr',
     }
 
-    API_VERSION = "60.0"
+    # If no API version is specified, defaults to the latest API.
+    API_VERSION = '74.0'
 
     # Defaults. Used in the absence of user-specified values.
     API_ENVIRONMENT = 'sandbox'
@@ -56,19 +61,9 @@ class PayPalConfig(object):
 
     ACK_SUCCESS = "SUCCESS"
     ACK_SUCCESS_WITH_WARNING = "SUCCESSWITHWARNING"
-    
-    # 0 being no debugging, 1 being some, 2 being lots.
-    DEBUG_LEVEL = 0
 
     # In seconds. Depending on your setup, this may need to be higher.
     HTTP_TIMEOUT = 15
-    
-    RESPONSE_KEYERROR = "AttributeError"
-    
-    # When True, return an AttributeError when the user tries to get an
-    # attribute on the response that does not exist. If False or None,
-    # return None for non-existant attribs.
-    KEY_ERROR = True
 
     def __init__(self, **kwargs):
         """
@@ -105,6 +100,9 @@ def __init__(self, **kwargs):
                     raise PayPalConfigError('Missing in PayPalConfig: %s ' % arg)
                 setattr(self, arg, kwargs[arg])
 
-        for arg in ('HTTP_TIMEOUT' , 'DEBUG_LEVEL' , 'RESPONSE_KEYERROR'):
+        for arg in ['HTTP_TIMEOUT']:
             if arg in kwargs:
                 setattr(self, arg, kwargs[arg])
+
+        logger.debug('PayPalConfig object instantiated with kwargs: %s' %
+            pformat(kwargs))