Merge pull request #386 from bear/feature/UpdateBackgroundImage_deprecation

Add Descriptive Deprecations

Author: jeremylow

doc/changelog.rst

@@ -4,18 +4,37 @@ Changelog
 Version 3.2
 ===========
 
+Deprecations
+------------
+
+Nothing is being deprecationed this version, however here's what's being deprecated as of v. 3.3.0:
+
+* :py:func:`twitter.api.Api.UpdateBackgroundImage`. Please make sure that your code does not call this function as it will be returning a hard error. There is no replace function. This was deprecated by Twitter around July 2015.
+
+* :py:func:`twitter.api.Api.PostMedia` will be removed. Please use :py:func:`twitter.api.Api.PostUpdate` instead.
+
+* :py:func:`twitter.api.Api.PostMultipleMedia`. Please use :py:func:`twitter.api.Api.PostUpdate` instead.
+
+* :py:func:`twitter.api.GetFriends` will no longer accept a `cursor` or `count` parameter. Please use :py:func:`twitter.api.GetFriendsPaged` instead.
+
+* :py:func:`twitter.api.GetFollowers` will no longer accept a `cursor` or `count` parameter. Please use :py:func:`twitter.api.GetFollowersPaged` instead.
+
+
 What's New
 ----------
 
+* We've added new deprecation warnings, so it's easier to track when things go away. All of python-twitter's deprecation warnings will be a subclass of :py:class:`twitter.error.PythonTwitterDeprecationWarning` and will have a version number associated with them such as :py:class:`twitter.error.PythonTwitterDeprecationWarning330`.
+
+
 * :py:class:`twitter.models.User` now contains a ``following`` attribute, which describes whether the authenticated user is following the User. `PR #351 <https://github.com/bear/python-twitter/pull/351>`_
 
-* :py:class:`twitter.models.DirectMessage` now contains a full :py:class:`twitter.models.User` object for both the ``DirectMessage.sender`` and ``DirectMessage.recipient`` properties. `PR #384 <https://github.com/bear/python-twitter/pull/384>`_.
+* :py:class:`twitter.models.DirectMessage` contains a full :py:class:`twitter.models.User` object for both the ``DirectMessage.sender`` and ``DirectMessage.recipient`` properties. `PR #384 <https://github.com/bear/python-twitter/pull/384>`_.
 
 * You can now upload Quicktime movies (``*.mov``). `PR #372 <https://github.com/bear/python-twitter/pull/372>`_.
 
 * If you have a whitelisted app, you can now get the authenticated user's email address through a call to :py:func:`twitter.api.Api.VerifyCredentials()`. If your app isn't whitelisted, no error is returned. `PR #376 <https://github.com/bear/python-twitter/pull/376>`_.
 
-* **Google App Engine support has been reintegrated into the library!** Check out `PR #383 <https://github.com/bear/python-twitter/pull/383>`_.
+* Google App Engine support has been reintegrated into the library. Check out `PR #383 <https://github.com/bear/python-twitter/pull/383>`_.
 
 What's Changed
 --------------

doc/twitter.rst

@@ -10,6 +10,11 @@ API
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: twitter.error
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Models
 ---------------------
 

tests/test_api_30.py

@@ -1854,3 +1854,10 @@ def testShowFriendship(self):
             twitter.TwitterError,
             lambda: self.api.ShowFriendship(target_screen_name='__jcbl__')
         )
+    @responses.activate
+    def test_UpdateBackgroundImage_deprecation(self):
+        responses.add(responses.POST, DEFAULT_URL, body='{}', status=200)
+        warnings.simplefilter("always")
+        with warnings.catch_warnings(record=True) as w:
+            resp = self.api.UpdateBackgroundImage(image='testdata/168NQ.jpg')
+            self.assertTrue(issubclass(w[0].category, DeprecationWarning))

twitter/api.py

@@ -20,6 +20,7 @@
 from __future__ import division
 from __future__ import print_function
 
+import json
 import sys
 import gzip
 import time
@@ -43,8 +44,17 @@
     from urllib import urlencode
     from urllib import __version__ as urllib_version
 
-from twitter import (__version__, _FileCache, json, DirectMessage, List,
-                     Status, Trend, TwitterError, User, UserStatus, Category)
+from twitter import (
+    __version__,
+    _FileCache,
+    Category,
+    DirectMessage,
+    List,
+    Status,
+    Trend,
+    User,
+    UserStatus,
+)
 
 from twitter.ratelimit import RateLimit
 
@@ -54,6 +64,11 @@
     parse_media_file,
     enf_type)
 
+from twitter.error import (
+    TwitterError,
+    PythonTwitterDeprecationWarning330,
+)
+
 
 warnings.simplefilter('always', DeprecationWarning)
 
@@ -1299,7 +1314,7 @@ def PostMedia(self,
             "PostUpdate() instead. Details of Twitter's deprecation can be "
             "found at: "
             "dev.twitter.com/rest/reference/post/statuses/update_with_media"),
-            DeprecationWarning)
+            PythonTwitterDeprecationWarning330)
 
         url = '%s/statuses/update_with_media.json' % self.base_url
 
@@ -1366,7 +1381,7 @@ def PostMultipleMedia(self, status, media, possibly_sensitive=None,
         warnings.warn((
             "This method is deprecated. Please use PostUpdate instead, "
             "passing a list of media that you would like to associate "
-            "with the updated."), DeprecationWarning, stacklevel=2)
+            "with the update."), PythonTwitterDeprecationWarning330)
         if type(media) is not list:
             raise TwitterError("Must by multiple media elements")
 
@@ -2613,8 +2628,9 @@ def _GetFriendsFollowers(self,
         if cursor is not None or count is not None:
             warnings.warn(
                 "Use of 'cursor' and 'count' parameters are deprecated as of "
-                "python-twitter 3.0. Please use GetFriendsPaged instead.",
-                DeprecationWarning, stacklevel=2)
+                "python-twitter 3.0. Please use GetFriendsPaged or "
+                "GetFollowersPaged instead.",
+                PythonTwitterDeprecationWarning330)
 
         count = 200
         cursor = -1
@@ -4320,6 +4336,10 @@ def UpdateBackgroundImage(self,
                               include_entities=False,
                               skip_status=False):
 
+        warnings.warn((
+            "This method has been deprecated by Twitter as of July 2015 and "
+            "will be removed in future versions of python-twitter."),
+            PythonTwitterDeprecationWarning330)
         url = '%s/account/update_profile_background_image.json' % (self.base_url)
         with open(image, 'rb') as image_file:
             encoded_image = base64.b64encode(image_file.read())

twitter/error.py

@@ -8,3 +8,13 @@ class TwitterError(Exception):
     def message(self):
         '''Returns the first argument used to construct this error.'''
         return self.args[0]
+
+
+class PythonTwitterDeprecationWarning(DeprecationWarning):
+    """Base class for python-twitter deprecation warnings"""
+    pass
+
+
+class PythonTwitterDeprecationWarning330(PythonTwitterDeprecationWarning):
+    """Warning for features to be removed in version 3.3.0"""
+    pass