Adding decorator for future deprecation (#214)

* Adding decorator for future deprecation

* Add test for decorator

* mark Audience Intelligence deprecation

* __qualname__ is not available for Python 2

- we can later change this back to use __qualname__ once we dropped the Python 2 support

Author: smaeda-ks

tests/test_utils.py

@@ -1,13 +1,30 @@
 import datetime
-from random import randint
 
 from twitter_ads.enum import GRANULARITY
-from twitter_ads.utils import to_time
+from twitter_ads.utils import to_time, Deprecated
 
 
 t = datetime.datetime(2006, 3, 21, 0, 0, 0)
 
+
 def test_to_time_based_on_granularity():
     for g in [None, GRANULARITY.HOUR, GRANULARITY.TOTAL]:
         assert to_time(t, g) == '2006-03-21T00:00:00Z'
     assert to_time(t, GRANULARITY.DAY) == '2006-03-21'
+
+
+def test_decorator_deprecated():
+    import warnings
+
+    class TestClass(object):
+        @classmethod
+        @Deprecated('deprecated API')
+        def test(self):
+            pass
+
+    with warnings.catch_warnings(record=True) as log:
+        TestClass.test()
+        assert len(log) == 1
+        assert issubclass(log[-1].category, DeprecationWarning)
+        assert "TestClass.test" in str(log[-1].message)
+        assert "deprecated API" in str(log[-1].message)

twitter_ads/audience.py

@@ -8,6 +8,7 @@
 from twitter_ads.error import BadRequest
 from twitter_ads.cursor import Cursor
 from twitter_ads import API_VERSION
+from twitter_ads.utils import Deprecated
 
 import json
 
@@ -174,6 +175,8 @@ def __get(klass, account, client, params):
             resource, headers=klass.HEADERS, body=params)
         return Cursor(klass, request, init_with=[account])
 
+    @Deprecated('This endpoint has been deprecated and will no longer be available '
+                'as of 2019-08-28')
     def conversations(self):
         """
         Get the conversation topics for an input targeting criteria
@@ -185,6 +188,8 @@ def conversations(self):
         }
         return self.__get(account=self.account, client=self.account.client, params=json.dumps(body))
 
+    @Deprecated('This endpoint has been deprecated and will no longer be available '
+                'as of 2019-08-28')
     def demographics(self):
         """
         Get the demographic breakdown for an input targeting criteria

twitter_ads/campaign.py

@@ -7,6 +7,7 @@
 from twitter_ads.http import Request
 from twitter_ads.cursor import Cursor
 from twitter_ads import API_VERSION
+from twitter_ads.utils import Deprecated
 
 
 class TargetingCriteria(Resource, Persistence, Batch):
@@ -343,6 +344,8 @@ def __init__(self):
             'Error! {name} cannot be instantiated.'.format(name=self.__class__.__name__))
 
     @classmethod
+    @Deprecated('This endpoint has been deprecated and will no longer be available '
+                'as of 2019-08-20')
     def preview(klass, account, **kwargs):
         """
         Returns an HTML preview of a tweet, either new or existing.

twitter_ads/creative.py

@@ -9,6 +9,7 @@
 from twitter_ads.enum import TRANSFORM
 from twitter_ads.http import Request
 from twitter_ads.resource import resource_property, Resource, Persistence, Analytics
+from twitter_ads.utils import Deprecated
 
 
 class PromotedAccount(Resource, Persistence):
@@ -324,6 +325,8 @@ class ScheduledTweet(Resource, Persistence):
     RESOURCE = '/' + API_VERSION + '/accounts/{account_id}/scheduled_tweets/{id}'
     PREVIEW = '/' + API_VERSION + '/accounts/{account_id}/scheduled_tweets/preview/{id}'
 
+    @Deprecated('This endpoint has been deprecated and will no longer be available '
+                'as of 2019-08-20')
     def preview(self):
         """
         Returns an HTML preview for a Scheduled Tweet.
@@ -363,6 +366,8 @@ class DraftTweet(Resource, Persistence):
     RESOURCE = '/' + API_VERSION + '/accounts/{account_id}/draft_tweets/{id}'
     PREVIEW = '/' + API_VERSION + '/accounts/{account_id}/draft_tweets/preview/{id}'
 
+    @Deprecated('This endpoint has been deprecated and will no longer be available '
+                'as of 2019-08-20')
     def preview(self, draft_tweet_id=None):
         """
         Preview a Draft Tweet on a mobile device.

twitter_ads/utils.py

@@ -4,6 +4,8 @@
 """Container for all helpers and utilities used throughout the Ads API SDK."""
 
 import datetime
+import warnings
+warnings.simplefilter('default', DeprecationWarning)
 from email.utils import formatdate
 from time import mktime
 
@@ -79,3 +81,19 @@ def extract_response_headers(headers):
     values['account_rate_limit_reset'] = headers.get('x-account-rate-limit-reset')
 
     return values
+
+
+class Deprecated(object):
+    def __init__(self, message):
+        self._message = message
+
+    def __call__(self, decorated, *args, **kwargs):
+        def wrapper(*args, **kwargs):
+            method = "{}.{}".format(str(args[0].__name__), str(decorated.__name__))
+            warnings.warn(
+                "{} => {}".format(method, self._message),
+                DeprecationWarning,
+                stacklevel=2
+            )
+            return decorated(*args, **kwargs)
+        return wrapper