Add configurable API version, default to '2017-02-14'

djstripe/settings.py

@@ -12,6 +12,7 @@
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.utils import six
+from django.utils.dateparse import date_re
 from django.utils.module_loading import import_string
 
 
@@ -150,6 +151,23 @@ def get_subscriber_model():
     return subscriber_model
 
 
+def get_api_version():
+    """Get the desired API version to use for Stripe requests."""
+    version = getattr(settings, 'DJSTRIPE_API_VERSION', None) or '2017-02-14'
+
+    if version == 'latest':
+        version = None
+    else:
+        if not date_re.match(version):
+            raise ImproperlyConfigured(
+                "STRIPE_VERSION must be a valid date in the form of "
+                "'YYYY-MM-DD', or the value 'latest' to specify the latest "
+                "version of the API as configured in your Stripe account. "
+                "Value provided: '{}'".format(version))
+
+    return version
+
+
 ZERO_DECIMAL_CURRENCIES = set([
     "bif", "clp", "djf", "gnf", "jpy", "kmf", "krw", "mga", "pyg", "rwf",
     "vnd", "vuv", "xaf", "xof", "xpf",

djstripe/stripe_objects.py

@@ -42,7 +42,12 @@
 from .managers import StripeObjectManager
 
 
-stripe.api_version = "2016-03-07"
+def set_stripe_api_version():
+    """Override the default API version used by the Stripe library."""
+    stripe.api_version = djstripe_settings.get_api_version()
+
+
+set_stripe_api_version()
 
 
 # ============================================================================ #

docs/settings.rst

@@ -2,6 +2,33 @@
 Settings
 =========
 
+DJSTRIPE_API_VERSION (='2017-02-14')
+====================================
+
+The API version used to communicate with the Stripe API is configurable, and
+defaults to the latest version that has been tested as working. Using a value
+other than the default is allowed, as a string in the format of YYYY-MM-DD, and
+it is also possible to specify `'latest'` in order to use the value configured
+in your Stripe account.
+
+For example, you can specify `'2017-01-27'` to use that API version:
+
+.. code-block:: python
+
+    DJSTRIPE_API_VERSION = '2017-01-27'
+
+However you do so at your own risk, as using a value other than the default
+might result in incompatibilities between Stripe and this library, especially
+if Stripe has labelled the differences between API versions as "Major". Even
+small differences such as a new enumeration value might cause issues.
+
+For this reason it is best to assume that only the default version is supported.
+
+For more information on API versioning, see the `stripe documentation`_.
+
+.. _stripe documentation: https://stripe.com/docs/upgrades
+
+
 DJSTRIPE_DEFAULT_PLAN (=None)
 =============================
 

setup.cfg

@@ -31,7 +31,7 @@ install_requires =
 	django-polymorphic >= 1.0
 	jsonfield >= 1.0.3
 	pytz >= 2016.6.1
-	stripe >= 1.41.1
+	stripe >= 1.53.0
 	tqdm >= 4.8.4
 	python-doc-inherit >= 0.3.0
 	mock-django >= 0.6.10

tests/test_settings.py

@@ -13,8 +13,8 @@
 from django.test.utils import override_settings
 from mock import patch
 
-from djstripe import settings
-from djstripe.settings import get_subscriber_model, get_callback_function
+from djstripe import settings as djstripe_settings
+from djstripe.settings import get_api_version, get_callback_function, get_subscriber_model
 
 
 class TestSubscriberModelRetrievalMethod(TestCase):
@@ -95,7 +95,7 @@ def test_get_callback_function_with_valid_func_callable(self):
         self.assertEquals("ok", func())
 
     @override_settings(DJSTRIPE_TEST_CALLBACK='foo.valid_callback')
-    @patch.object(settings, 'import_string', return_value=(lambda: "ok"))
+    @patch.object(djstripe_settings, 'import_string', return_value=(lambda: "ok"))
     def test_get_callback_function_with_valid_string_callable(self, import_string_mock):
         func = get_callback_function("DJSTRIPE_TEST_CALLBACK")
         self.assertEquals("ok", func())
@@ -107,7 +107,7 @@ def test_get_callback_function_import_error(self):
             get_callback_function("DJSTRIPE_TEST_CALLBACK")
 
     @override_settings(DJSTRIPE_TEST_CALLBACK='foo.invalid_callback')
-    @patch.object(settings, 'import_string', return_value="not_callable")
+    @patch.object(djstripe_settings, 'import_string', return_value="not_callable")
     def test_get_callback_function_with_non_callable_string(self, import_string_mock):
         with self.assertRaises(ImproperlyConfigured):
             get_callback_function("DJSTRIPE_TEST_CALLBACK")
@@ -117,3 +117,24 @@ def test_get_callback_function_with_non_callable_string(self, import_string_mock
     def test_get_callback_function_(self):
         with self.assertRaises(ImportError):
             get_callback_function("DJSTRIPE_TEST_CALLBACK")
+
+
+class TestGetApiVersion(TestCase):
+
+    @override_settings(DJSTRIPE_API_VERSION=None)
+    def test_with_default(self):
+        self.assertEquals('2017-02-14', get_api_version())
+
+    @override_settings(DJSTRIPE_API_VERSION='latest')
+    def test_with_latest(self):
+        self.assertIsNone(get_api_version())
+
+    @override_settings(DJSTRIPE_API_VERSION='2016-03-07')
+    def test_with_valid_date(self):
+        self.assertEquals('2016-03-07', get_api_version())
+
+    @override_settings(DJSTRIPE_API_VERSION='foobar')
+    def test_with_invalid_date(self):
+        err = 'must be a valid date'
+        with self.assertRaisesRegexp(ImproperlyConfigured, err):
+            get_api_version()