Deprecated non-standard Invoice.status (dj-stripe#1078)

renamed to Invoice.legacy_status, to make way for the Stripe field (preparation for dj-stripe#1020).

HISTORY.rst

@@ -41,6 +41,7 @@ History
   deleting it from our database,  to match Stripe's behaviour (#599).
 - Added missing ``Refund.reason`` value, increases field width (#1075).
 - Fixed ``Refund.status`` definition, reduces field width (#1076).
+- Deprecated non-standard ``Invoice.status`` (renamed to ``Invoice.legacy_status``) to make way for the Stripe field (preparation for #1020).
 
 Warning about safe uninstall of jsonfield on upgrade
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

djstripe/models/billing.py

@@ -274,7 +274,7 @@ class BaseInvoice(StripeModel):
         related_name="latest_%(class)s",
         help_text="The latest charge generated for this invoice, if any.",
     )
-    # deprecated, will be removed in 2.2
+    # deprecated, will be removed in 2.3
     closed = models.NullBooleanField(
         default=False,
         help_text="Whether or not the invoice is still trying to collect payment."
@@ -372,7 +372,7 @@ class BaseInvoice(StripeModel):
     footer = models.TextField(
         max_length=5000, blank=True, help_text="Footer displayed on the invoice."
     )
-    # deprecated, will be removed in 2.2
+    # deprecated, will be removed in 2.3
     forgiven = models.NullBooleanField(
         default=False,
         help_text="Whether or not the invoice has been forgiven. "
@@ -542,15 +542,15 @@ def _manipulate_stripe_object_hook(cls, data):
         # see https://stripe.com/docs/upgrades#2018-11-08
 
         if "closed" not in data:
-            # TODO - drop this in 2.2, use auto_advance instead
+            # TODO - drop this in 2.3, use auto_advance instead
             # https://stripe.com/docs/billing/invoices/migrating-new-invoice-states#autoadvance
             if "auto_advance" in data:
                 data["closed"] = not data["auto_advance"]
             else:
                 data["closed"] = False
 
         if "forgiven" not in data:
-            # TODO - drop this in 2.2, use status == "uncollectible" instead
+            # TODO - drop this in 2.3, use status == "uncollectible" instead
             if "status" in data:
                 data["forgiven"] = data["status"] == "uncollectible"
             else:
@@ -671,6 +671,16 @@ def retry(self):
 
     @property
     def status(self):
+        warnings.warn(
+            "Invoice.status will be redefined in djstripe 2.3, use "
+            "Invoice.legacy_status to keep the old values",
+            DeprecationWarning,
+        )
+
+        return self.legacy_status
+
+    @property
+    def legacy_status(self):
         """
         Attempts to label this invoice with a status.
         Note that an invoice can be more than one of the choices.

tests/test_invoice.py

@@ -489,7 +489,10 @@ def test_status_paid(
 
         invoice = Invoice.sync_from_stripe_data(deepcopy(FAKE_INVOICE))
 
-        self.assertEqual(Invoice.STATUS_PAID, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_PAID, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_PAID, invoice.legacy_status)
 
         self.assert_fks(invoice, expected_blank_fks=self.default_expected_blank_fks)
 
@@ -537,7 +540,10 @@ def test_status_open(
         invoice_data.update({"paid": False, "closed": False})
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_OPEN, invoice.legacy_status)
 
         self.assert_fks(invoice, expected_blank_fks=self.default_expected_blank_fks)
 
@@ -585,7 +591,10 @@ def test_status_forgiven(
         invoice_data.update({"paid": False, "closed": False, "forgiven": True})
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.legacy_status)
 
         self.assert_fks(invoice, expected_blank_fks=self.default_expected_blank_fks)
 
@@ -637,7 +646,10 @@ def test_status_forgiven_deprecated(
         invoice_data["status"] = "uncollectible"
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_FORGIVEN, invoice.legacy_status)
 
     @patch(
         "djstripe.models.Account.get_default_account",
@@ -686,7 +698,10 @@ def test_status_forgiven_default(
         invoice_data.pop("forgiven", None)  # TODO remove
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_OPEN, invoice.legacy_status)
 
     @patch(
         "djstripe.models.Account.get_default_account",
@@ -732,7 +747,10 @@ def test_status_closed(
         invoice_data.update({"paid": False})
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_CLOSED, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_CLOSED, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_CLOSED, invoice.legacy_status)
 
         self.assert_fks(invoice, expected_blank_fks=self.default_expected_blank_fks)
 
@@ -784,7 +802,11 @@ def test_status_closed_deprecated(
 
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_CLOSED, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_CLOSED, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_CLOSED, invoice.legacy_status)
+
         self.assertEqual(invoice.auto_advance, invoice_data["auto_advance"])
 
     @patch(
@@ -837,7 +859,10 @@ def test_status_closed_default(
 
         invoice = Invoice.sync_from_stripe_data(invoice_data)
 
-        self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(Invoice.STATUS_OPEN, invoice.status)
+
+        self.assertEqual(Invoice.STATUS_OPEN, invoice.legacy_status)
 
     @patch(
         "djstripe.models.Account.get_default_account",