From b774d186e353de9175ba81e5bdfe083e5c9c38b1 Mon Sep 17 00:00:00 2001 From: Jeremy Low Date: Wed, 23 Mar 2016 20:46:33 -0400 Subject: [PATCH 1/5] fix up "id" kwargs. "status_id" is more common within the api, but there are a couple methods that use "id" to spec the same thing, which is confusing and inconsistent. "woeid" avoids shadowing a builtin, but is also more expressive. --- twitter/api.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/twitter/api.py b/twitter/api.py index f00f0d0d..40418c98 100644 --- a/twitter/api.py +++ b/twitter/api.py @@ -1,7 +1,6 @@ #!/usr/bin/env python # -# vim: sw=2 ts=2 sts=2 # # Copyright 2007 The Python-Twitter Developers # @@ -490,9 +489,9 @@ def GetTrendsCurrent(self, exclude=None): Returns: A list with 10 entries. Each entry contains a trend. """ - return self.GetTrendsWoeid(id=1, exclude=exclude) + return self.GetTrendsWoeid(woeid=1, exclude=exclude) - def GetTrendsWoeid(self, id, exclude=None): + def GetTrendsWoeid(self, woeid, exclude=None): """Return the top 10 trending topics for a specific WOEID, if trending information is available for it. @@ -507,7 +506,7 @@ def GetTrendsWoeid(self, id, exclude=None): A list with 10 entries. Each entry contains a trend. """ url = '%s/trends/place.json' % (self.base_url) - parameters = {'id': id} + parameters = {'id': woeid} if exclude: parameters['exclude'] = exclude @@ -771,7 +770,7 @@ def GetStatus(self, return Status.NewFromJsonDict(data) def GetStatusOembed(self, - id=None, + status_id=None, url=None, maxwidth=None, hide_media=False, @@ -2810,7 +2809,7 @@ def LookupFriendship(self, def CreateFavorite(self, status=None, - id=None, + status_id=None, include_entities=True): """Favorites the specified status object or id as the authenticating user. @@ -2845,7 +2844,7 @@ def CreateFavorite(self, def DestroyFavorite(self, status=None, - id=None, + status_id=None, include_entities=True): """Un-Favorites the specified status object or id as the authenticating user. From 86142a3844f413d9ff440d70ba17c7bf85b46ae9 Mon Sep 17 00:00:00 2001 From: Jeremy Low Date: Wed, 23 Mar 2016 21:05:35 -0400 Subject: [PATCH 2/5] adds documentation re change to "id" kwargs --- doc/migration_v30.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/migration_v30.rst b/doc/migration_v30.rst index 8eaa9a3d..d933cd58 100644 --- a/doc/migration_v30.rst +++ b/doc/migration_v30.rst @@ -4,6 +4,16 @@ Migration from v2 to v3 Changes to Existing Methods =========================== +:py:func:`twitter.api.Api.CreateFavorite` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* kwarg param has been changed to ``status_id`` from ``id`` to be consistent + with other method calls and avoid shadowing builtin function ``id``. + +:py:func:`twitter.api.Api.DestroyFavorite` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* kwarg param has been changed to ``status_id`` from ``id`` to be consistent + with other method calls and avoid shadowing builtin function ``id``. + :py:func:`twitter.api.Api.GetBlocks` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * Method no longer accepts parameters ``user_id`` or ``screen_name`` as these are not honored by Twitter. The data returned will be for the authenticated user only. @@ -35,10 +45,22 @@ Changes to Existing Methods +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * No longer accepts ``cursor`` parameter. If you require granular control over the paging of the twitter.list.List members, please user twitter.api.Api.GetListMembersPaged instead. + +:py:func:`twitter.api.Api.GetStatusOembed` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of + the Api and to avoid shadowing a builtin. + :py:func:`twitter.api.Api.GetSearch` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * Adds ``raw_query`` method. See :ref:`raw_queries` for more information. + +:py:func:`twitter.api.Api.GetTrendsWoeid` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``id`` has been changed to ``woeid`` in order to avoid shadowing + a builtin and be more descriptive. + :py:func:`twitter.api.Api.GetUserStream` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * Parameter 'stall_warning' is now 'stall_warnings' in line with GetStreamFilter and Twitter's naming convention. This should now actually return stall warnings, whereas it did not have any effect previously. From 4428fb08cf5046c88ebfcf7602c31ae71c008188 Mon Sep 17 00:00:00 2001 From: Jeremy Low Date: Wed, 23 Mar 2016 21:06:19 -0400 Subject: [PATCH 3/5] adds "docs" target to makefile --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index a4cb08c0..970b001e 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,7 @@ help: @echo " env install all production dependencies" @echo " dev install all dev and production dependencies (virtualenv is assumed)" + @echo " docs build documentation" @echo " clean remove unwanted stuff" @echo " lint check style with flake8" @echo " test run tests" @@ -23,7 +24,10 @@ clean: rm -fr dist find . -name '*.pyc' -exec rm -f {} \; find . -name '*.pyo' -exec rm -f {} \; - find . -name '*~' -exec rm -f {} \; + find . -name '*~' ! -name '*.un~' -exec rm -f {} \; + +docs: + $(MAKE) -C doc html lint: flake8 twitter > violations.flake8.txt From 28703591cd9031ed87138725cdb3f51117754ece Mon Sep 17 00:00:00 2001 From: Jeremy Low Date: Sun, 27 Mar 2016 18:54:26 -0400 Subject: [PATCH 4/5] fix up a few more "id" params & add documentation for same. --- doc/migration_v30.rst | 9 +++++++++ twitter/api.py | 44 +++++++++++++++++++++---------------------- 2 files changed, 31 insertions(+), 22 deletions(-) diff --git a/doc/migration_v30.rst b/doc/migration_v30.rst index d933cd58..acf89472 100644 --- a/doc/migration_v30.rst +++ b/doc/migration_v30.rst @@ -14,6 +14,11 @@ Changes to Existing Methods * kwarg param has been changed to ``status_id`` from ``id`` to be consistent with other method calls and avoid shadowing builtin function ``id``. +:py:func:`twitter.api.Api.DestroyStatus` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of + the Api and to avoid shadowing a builtin. + :py:func:`twitter.api.Api.GetBlocks` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * Method no longer accepts parameters ``user_id`` or ``screen_name`` as these are not honored by Twitter. The data returned will be for the authenticated user only. @@ -45,6 +50,10 @@ Changes to Existing Methods +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * No longer accepts ``cursor`` parameter. If you require granular control over the paging of the twitter.list.List members, please user twitter.api.Api.GetListMembersPaged instead. +:py:func:`twitter.api.Api.GetStatus` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of + the Api and to avoid shadowing a builtin. :py:func:`twitter.api.Api.GetStatusOembed` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/twitter/api.py b/twitter/api.py index 40418c98..feb2f709 100644 --- a/twitter/api.py +++ b/twitter/api.py @@ -106,15 +106,15 @@ class Api(object): >>> api.GetReplies() >>> api.GetUserTimeline(user) >>> api.GetHomeTimeline() - >>> api.GetStatus(id) - >>> api.DestroyStatus(id) + >>> api.GetStatus(status_id) + >>> api.DestroyStatus(status_id) >>> api.GetFriends(user) >>> api.GetFollowers() >>> api.GetFeatured() >>> api.GetDirectMessages() >>> api.GetSentDirectMessages() >>> api.PostDirectMessage(user, text) - >>> api.DestroyDirectMessage(id) + >>> api.DestroyDirectMessage(message_id) >>> api.DestroyFriendship(user) >>> api.CreateFriendship(user) >>> api.LookupFriendship(user) @@ -722,14 +722,14 @@ def GetUserTimeline(self, return [Status.NewFromJsonDict(x) for x in data] def GetStatus(self, - id, + status_id, trim_user=False, include_my_retweet=True, include_entities=True): - """Returns a single status message, specified by the id parameter. + """Returns a single status message, specified by the status_id parameter. Args: - id: + status_id: The numeric ID of the status you are trying to retrieve. trim_user: When set to True, each tweet returned in a timeline will include @@ -753,9 +753,9 @@ def GetStatus(self, parameters = {} try: - parameters['id'] = int(id) + parameters['id'] = int(status_id) except ValueError: - raise TwitterError({'message': "'id' must be an integer."}) + raise TwitterError({'message': "'status_id' must be an integer."}) if trim_user: parameters['trim_user'] = 1 @@ -851,7 +851,7 @@ def GetStatusOembed(self, return data - def DestroyStatus(self, id, trim_user=False): + def DestroyStatus(self, status_id, trim_user=False): """Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified @@ -865,10 +865,10 @@ def DestroyStatus(self, id, trim_user=False): A twitter.Status instance representing the destroyed status message """ try: - post_data = {'id': int(id)} + post_data = {'id': int(status_id)} except ValueError: raise TwitterError({'message': "id must be an integer"}) - url = '%s/statuses/destroy/%s.json' % (self.base_url, id) + url = '%s/statuses/destroy/%s.json' % (self.base_url, status_id) if trim_user: post_data['trim_user'] = 1 @@ -2639,7 +2639,7 @@ def PostDirectMessage(self, return DirectMessage.NewFromJsonDict(data) - def DestroyDirectMessage(self, id, include_entities=True): + def DestroyDirectMessage(self, message_id, include_entities=True): """Destroys the direct message specified in the required ID parameter. The twitter.Api instance must be authenticated, and the @@ -2647,13 +2647,13 @@ def DestroyDirectMessage(self, id, include_entities=True): message. Args: - id: The id of the direct message to be destroyed + message_id: The id of the direct message to be destroyed Returns: A twitter.DirectMessage instance representing the message destroyed """ url = '%s/direct_messages/destroy.json' % self.base_url - data = {'id': id} + data = {'id': message_id} if not include_entities: data['include_entities'] = 'false' @@ -2816,7 +2816,7 @@ def CreateFavorite(self, Returns the favorite status when successful. Args: - id: + status_id: The id of the twitter status to mark as a favorite. [Optional] status: The twitter.Status object to mark as a favorite. [Optional] @@ -2828,12 +2828,12 @@ def CreateFavorite(self, """ url = '%s/favorites/create.json' % self.base_url data = {} - if id: - data['id'] = id + if status_id: + data['id'] = status_id elif status: data['id'] = status.id else: - raise TwitterError({'message': "Specify id or status"}) + raise TwitterError({'message': "Specify status_id or status"}) if not include_entities: data['include_entities'] = 'false' @@ -2851,7 +2851,7 @@ def DestroyFavorite(self, Returns the un-favorited status when successful. Args: - id: + status_id: The id of the twitter status to unmark as a favorite. [Optional] status: The twitter.Status object to unmark as a favorite. [Optional] @@ -2863,12 +2863,12 @@ def DestroyFavorite(self, """ url = '%s/favorites/destroy.json' % self.base_url data = {} - if id: - data['id'] = id + if status_id: + data['id'] = status_id elif status: data['id'] = status.id else: - raise TwitterError({'message': "Specify id or status"}) + raise TwitterError({'message': "Specify status_id or status"}) if not include_entities: data['include_entities'] = 'false' From 7dcdf61fe93fa2a65cd1555e7650021fc6f7081e Mon Sep 17 00:00:00 2001 From: Jeremy Low Date: Sun, 27 Mar 2016 19:17:41 -0400 Subject: [PATCH 5/5] changes postretweet & destroyblock to use status_id and user_id, respectively --- doc/migration_v30.rst | 13 ++++++++++--- twitter/api.py | 36 ++++++++++++++++++------------------ 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/doc/migration_v30.rst b/doc/migration_v30.rst index acf89472..d47f63b0 100644 --- a/doc/migration_v30.rst +++ b/doc/migration_v30.rst @@ -14,9 +14,14 @@ Changes to Existing Methods * kwarg param has been changed to ``status_id`` from ``id`` to be consistent with other method calls and avoid shadowing builtin function ``id``. +:py:func:`twitter.api.Api.DestroyBlock` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``id`` has been changed to ``user_id`` in order to avoid shadowing + a builtin and be more descriptive. + :py:func:`twitter.api.Api.DestroyStatus` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of +* kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of the Api and to avoid shadowing a builtin. :py:func:`twitter.api.Api.GetBlocks` @@ -74,10 +79,8 @@ Changes to Existing Methods +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * Parameter 'stall_warning' is now 'stall_warnings' in line with GetStreamFilter and Twitter's naming convention. This should now actually return stall warnings, whereas it did not have any effect previously. - :py:func:`twitter.api.Api.LookupFriendship` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - * Method will now accept a list for either ``user_id`` or ``screen_name``. The list can contain either ints, strings, or :py:mod:`twitter.user.User` objects for either ``user_id`` or ``screen_name``. * Return value is a list of :py:mod:`twitter.user.UserStatus` objects. @@ -87,6 +90,10 @@ Changes to Existing Methods * ``media_additional_owners`` should be a list of user ids representing Twitter users that should be able to use the uploaded media in their tweets. If you pass a list of media, then **additional owners will apply to each object.** If you need more granular control, please use the UploadMedia* methods. * ``media_category``: Only for use with the AdsAPI. See https://dev.twitter.com/ads/creative/promoted-video-overview if this applies to your application. +:py:func:`twitter.api.Api.PostRetweet` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +* Kwarg ``original_id`` has been changed to ``status_id`` in order to avoid shadowing + a builtin and be more descriptive. Deprecation =========== diff --git a/twitter/api.py b/twitter/api.py index feb2f709..590c2ab2 100644 --- a/twitter/api.py +++ b/twitter/api.py @@ -785,7 +785,7 @@ def GetStatusOembed(self, Specify tweet by the id or url parameter. Args: - id: + status_id: The numeric ID of the status you are trying to embed. url: The url of the status you are trying to embed. @@ -815,15 +815,15 @@ def GetStatusOembed(self, parameters = {} - if id is not None: + if status_id is not None: try: - parameters['id'] = int(id) + parameters['id'] = int(status_id) except ValueError: - raise TwitterError({'message': "'id' must be an integer."}) + raise TwitterError({'message': "'status_id' must be an integer."}) elif url is not None: parameters['url'] = url else: - raise TwitterError({'message': "Must specify either 'id' or 'url'"}) + raise TwitterError({'message': "Must specify either 'status_id' or 'url'"}) if maxwidth is not None: parameters['maxwidth'] = maxwidth @@ -858,7 +858,7 @@ def DestroyStatus(self, status_id, trim_user=False): status. Args: - id: + status_id: The numerical ID of the status you're trying to destroy. Returns: @@ -867,7 +867,7 @@ def DestroyStatus(self, status_id, trim_user=False): try: post_data = {'id': int(status_id)} except ValueError: - raise TwitterError({'message': "id must be an integer"}) + raise TwitterError({'message': "status_id must be an integer"}) url = '%s/statuses/destroy/%s.json' % (self.base_url, status_id) if trim_user: post_data['trim_user'] = 1 @@ -1405,11 +1405,11 @@ def PostUpdates(self, return results - def PostRetweet(self, original_id, trim_user=False): + def PostRetweet(self, status_id, trim_user=False): """Retweet a tweet with the Retweet API. Args: - original_id: + status_id: The numerical id of the tweet that will be retweeted trim_user: If True the returned payload will only contain the user IDs, @@ -1420,13 +1420,13 @@ def PostRetweet(self, original_id, trim_user=False): A twitter.Status instance representing the original tweet with retweet details embedded. """ try: - if int(original_id) <= 0: - raise TwitterError({'message': "'original_id' must be a positive number"}) + if int(status_id) <= 0: + raise TwitterError({'message': "'status_id' must be a positive number"}) except ValueError: - raise TwitterError({'message': "'original_id' must be an integer"}) + raise TwitterError({'message': "'status_id' must be an integer"}) - url = '%s/statuses/retweet/%s.json' % (self.base_url, original_id) - data = {'id': original_id} + url = '%s/statuses/retweet/%s.json' % (self.base_url, status_id) + data = {'id': status_id} if trim_user: data['trim_user'] = 'true' resp = self._RequestUrl(url, 'POST', data=data) @@ -1770,7 +1770,7 @@ def GetBlocksIDs(self, return result - def DestroyBlock(self, id, trim_user=False): + def DestroyBlock(self, user_id, trim_user=False): """Destroys the block for the user specified by the required ID parameter. @@ -1778,16 +1778,16 @@ def DestroyBlock(self, id, trim_user=False): required ID parameter. Args: - id: + user_id: The numerical ID of the user to be un-blocked. Returns: A twitter.User instance representing the un-blocked user. """ try: - post_data = {'user_id': int(id)} + post_data = {'user_id': int(user_id)} except ValueError: - raise TwitterError({'message': "id must be an integer"}) + raise TwitterError({'message': "user_id must be an integer"}) url = '%s/blocks/destroy.json' % (self.base_url) if trim_user: post_data['trim_user'] = 1