Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign upGitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
| # -*- coding: utf-8 -*- | |
| """ | |
| twython.endpoints | |
| ~~~~~~~~~~~~~~~~~ | |
| This module provides a mixin for a :class:`Twython <Twython>` instance. | |
| Parameters that need to be embedded in the API url just need to be passed | |
| as a keyword argument. | |
| e.g. Twython.retweet(id=12345) | |
| Official documentation for Twitter API endpoints can be found at: | |
| https://developer.twitter.com/en/docs/api-reference-index | |
| """ | |
| import json | |
| import os | |
| import warnings | |
| from io import BytesIO | |
| from time import sleep | |
| #try: | |
| #from StringIO import StringIO | |
| #except ImportError: | |
| #from io import StringIO | |
| from .advisory import TwythonDeprecationWarning | |
| class EndpointsMixin(object): | |
| # Timelines | |
| def get_mentions_timeline(self, **params): | |
| """Returns the 20 most recent mentions (tweets containing a users's | |
| @screen_name) for the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline | |
| """ | |
| return self.get('statuses/mentions_timeline', params=params) | |
| get_mentions_timeline.iter_mode = 'id' | |
| def get_user_timeline(self, **params): | |
| """Returns a collection of the most recent Tweets posted by the user | |
| indicated by the ``screen_name`` or ``user_id`` parameters. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline | |
| """ | |
| return self.get('statuses/user_timeline', params=params) | |
| get_user_timeline.iter_mode = 'id' | |
| def get_home_timeline(self, **params): | |
| """Returns a collection of the most recent Tweets and retweets | |
| posted by the authenticating user and the users they follow. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline | |
| """ | |
| return self.get('statuses/home_timeline', params=params) | |
| get_home_timeline.iter_mode = 'id' | |
| def retweeted_of_me(self, **params): | |
| """Returns the most recent tweets authored by the authenticating user | |
| that have been retweeted by others. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me | |
| """ | |
| return self.get('statuses/retweets_of_me', params=params) | |
| retweeted_of_me.iter_mode = 'id' | |
| # Tweets | |
| def get_retweets(self, **params): | |
| """Returns up to 100 of the first retweets of a given tweet. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id | |
| """ | |
| return self.get('statuses/retweets/%s' % params.get('id'), | |
| params=params) | |
| def show_status(self, **params): | |
| """Returns a single Tweet, specified by the ``id`` parameter | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id | |
| """ | |
| return self.get('statuses/show/%s' % params.get('id'), params=params) | |
| def lookup_status(self, **params): | |
| """Returns fully-hydrated tweet objects for up to 100 tweets per | |
| request, as specified by comma-separated values passed to the ``id`` | |
| parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup | |
| """ | |
| return self.post('statuses/lookup', params=params) | |
| def destroy_status(self, **params): | |
| """Destroys the status specified by the required ``id`` parameter | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id | |
| """ | |
| return self.post('statuses/destroy/%s' % params.get('id')) | |
| def update_status(self, **params): | |
| """Updates the authenticating user's current status, also known as tweeting | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update | |
| """ | |
| return self.post('statuses/update', params=params) | |
| def retweet(self, **params): | |
| """Retweets a tweet specified by the ``id`` parameter | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id | |
| """ | |
| return self.post('statuses/retweet/%s' % params.get('id')) | |
| def update_status_with_media(self, **params): # pragma: no cover | |
| """Updates the authenticating user's current status and attaches media | |
| for upload. In other words, it creates a Tweet with a picture attached. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update_with_media | |
| """ | |
| warnings.warn( | |
| 'This method is deprecated. You should use Twython.upload_media instead.', | |
| TwythonDeprecationWarning, | |
| stacklevel=2 | |
| ) | |
| return self.post('statuses/update_with_media', params=params) | |
| def upload_media(self, **params): | |
| """Uploads media file to Twitter servers. The file will be available to be attached | |
| to a status for 60 minutes. To attach to a update, pass a list of returned media ids | |
| to the :meth:`update_status` method using the ``media_ids`` param. | |
| Docs: | |
| https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload | |
| """ | |
| # https://developer.twitter.com/en/docs/media/upload-media/api-reference/get-media-upload-status | |
| if params and params.get('command', '') == 'STATUS': | |
| return self.get('https://upload.twitter.com/1.1/media/upload.json', params=params) | |
| return self.post('https://upload.twitter.com/1.1/media/upload.json', params=params) | |
| def create_metadata(self, **params): | |
| """ Adds metadata to a media element, such as image descriptions for visually impaired. | |
| Docs: | |
| https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-metadata-create | |
| """ | |
| params = json.dumps(params) | |
| return self.post("https://upload.twitter.com/1.1/media/metadata/create.json", params=params) | |
| def upload_video(self, media, media_type, media_category=None, size=None, check_progress=False): | |
| """Uploads video file to Twitter servers in chunks. The file will be available to be attached | |
| to a status for 60 minutes. To attach to a update, pass a list of returned media ids | |
| to the :meth:`update_status` method using the ``media_ids`` param. | |
| Upload happens in 3 stages: | |
| - INIT call with size of media to be uploaded(in bytes). If this is more than 15mb, twitter will return error. | |
| - APPEND calls each with media chunk. This returns a 204(No Content) if chunk is received. | |
| - FINALIZE call to complete media upload. This returns media_id to be used with status update. | |
| Twitter media upload api expects each chunk to be not more than 5mb. We are sending chunk of 1mb each. | |
| Docs: | |
| https://developer.twitter.com/en/docs/media/upload-media/uploading-media/chunked-media-upload | |
| """ | |
| upload_url = 'https://upload.twitter.com/1.1/media/upload.json' | |
| if not size: | |
| media.seek(0, os.SEEK_END) | |
| size = media.tell() | |
| media.seek(0) | |
| # Stage 1: INIT call | |
| params = { | |
| 'command': 'INIT', | |
| 'media_type': media_type, | |
| 'total_bytes': size, | |
| 'media_category': media_category | |
| } | |
| response_init = self.post(upload_url, params=params) | |
| media_id = response_init['media_id'] | |
| # Stage 2: APPEND calls with 1mb chunks | |
| segment_index = 0 | |
| while True: | |
| data = media.read(1*1024*1024) | |
| if not data: | |
| break | |
| media_chunk = BytesIO() | |
| media_chunk.write(data) | |
| media_chunk.seek(0) | |
| params = { | |
| 'command': 'APPEND', | |
| 'media_id': media_id, | |
| 'segment_index': segment_index, | |
| 'media': media_chunk, | |
| } | |
| self.post(upload_url, params=params) | |
| segment_index += 1 | |
| # Stage 3: FINALIZE call to complete upload | |
| params = { | |
| 'command': 'FINALIZE', | |
| 'media_id': media_id | |
| } | |
| response = self.post(upload_url, params=params) | |
| # Only get the status if explicity asked to | |
| # Default to False | |
| if check_progress: | |
| # Stage 4: STATUS call if still processing | |
| params = { | |
| 'command': 'STATUS', | |
| 'media_id': media_id | |
| } | |
| # added code to handle if media_category is NOT set and check_progress=True | |
| # the API will return a NoneType object in this case | |
| try: | |
| processing_state = response.get('processing_info').get('state') | |
| except AttributeError: | |
| return response | |
| if processing_state: | |
| while (processing_state == 'pending' or processing_state == 'in_progress') : | |
| # get the secs to wait | |
| check_after_secs = response.get('processing_info').get('check_after_secs') | |
| if check_after_secs: | |
| sleep(check_after_secs) | |
| response = self.get(upload_url, params=params) | |
| # get new state after waiting | |
| processing_state = response.get('processing_info').get('state') | |
| return response | |
| def get_oembed_tweet(self, **params): | |
| """Returns information allowing the creation of an embedded | |
| representation of a Tweet on third party sites. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed | |
| """ | |
| return self.get('oembed', params=params) | |
| def get_retweeters_ids(self, **params): | |
| """Returns a collection of up to 100 user IDs belonging to users who | |
| have retweeted the tweet specified by the ``id`` parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids | |
| """ | |
| return self.get('statuses/retweeters/ids', params=params) | |
| get_retweeters_ids.iter_mode = 'cursor' | |
| get_retweeters_ids.iter_key = 'ids' | |
| # Search | |
| def search(self, **params): | |
| """Returns a collection of relevant Tweets matching a specified query. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets | |
| """ | |
| return self.get('search/tweets', params=params) | |
| search.iter_mode = 'id' | |
| search.iter_key = 'statuses' | |
| search.iter_metadata = 'search_metadata' | |
| # Direct Messages | |
| def get_direct_messages(self, **params): | |
| """Returns the 20 most recent direct messages sent to the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events | |
| """ | |
| return self.get('direct_messages/events/list', params=params) | |
| get_direct_messages.iter_mode = 'id' | |
| def get_sent_messages(self, **params): | |
| """Returns the 20 most recent direct messages sent by the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message | |
| """ | |
| return self.get('direct_messages/sent', params=params) | |
| get_sent_messages.iter_mode = 'id' | |
| def get_direct_message(self, **params): | |
| """Returns a single direct message, specified by an ``id`` parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event | |
| """ | |
| return self.get('direct_messages/events/show', params=params) | |
| def destroy_direct_message(self, **params): | |
| """Destroys the direct message specified in the required ``id`` parameter | |
| Docs: | |
| https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event | |
| """ | |
| return self.delete('direct_messages/events/destroy', params=params) | |
| def send_direct_message(self, **params): | |
| """Sends a new direct message to the specified user from the | |
| authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event | |
| """ | |
| return self.post('direct_messages/events/new', params=params, json_encoded=True) | |
| # Friends & Followers | |
| def get_user_ids_of_blocked_retweets(self, **params): | |
| """Returns a collection of user_ids that the currently authenticated | |
| user does not want to receive retweets from. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids | |
| """ | |
| return self.get('friendships/no_retweets/ids', params=params) | |
| def get_friends_ids(self, **params): | |
| """Returns a cursored collection of user IDs for every user the | |
| specified user is following (otherwise known as their "friends"). | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids | |
| """ | |
| return self.get('friends/ids', params=params) | |
| get_friends_ids.iter_mode = 'cursor' | |
| get_friends_ids.iter_key = 'ids' | |
| def get_followers_ids(self, **params): | |
| """Returns a cursored collection of user IDs for every user | |
| following the specified user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids | |
| """ | |
| return self.get('followers/ids', params=params) | |
| get_followers_ids.iter_mode = 'cursor' | |
| get_followers_ids.iter_key = 'ids' | |
| def lookup_friendships(self, **params): | |
| """Returns the relationships of the authenticating user to the | |
| comma-separated list of up to 100 ``screen_names`` or ``user_ids`` provided. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup | |
| """ | |
| return self.get('friendships/lookup', params=params) | |
| def get_incoming_friendship_ids(self, **params): | |
| """Returns a collection of numeric IDs for every user who has a | |
| pending request to follow the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming | |
| """ | |
| return self.get('friendships/incoming', params=params) | |
| get_incoming_friendship_ids.iter_mode = 'cursor' | |
| get_incoming_friendship_ids.iter_key = 'ids' | |
| def get_outgoing_friendship_ids(self, **params): | |
| """Returns a collection of numeric IDs for every protected user for | |
| whom the authenticating user has a pending follow request. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing | |
| """ | |
| return self.get('friendships/outgoing', params=params) | |
| get_outgoing_friendship_ids.iter_mode = 'cursor' | |
| get_outgoing_friendship_ids.iter_key = 'ids' | |
| def create_friendship(self, **params): | |
| """Allows the authenticating users to follow the user specified | |
| in the ``id`` parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create | |
| """ | |
| return self.post('friendships/create', params=params) | |
| def destroy_friendship(self, **params): | |
| """Allows the authenticating user to unfollow the user specified | |
| in the ``id`` parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy | |
| """ | |
| return self.post('friendships/destroy', params=params) | |
| def update_friendship(self, **params): | |
| """Allows one to enable or disable retweets and device notifications | |
| from the specified user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update | |
| """ | |
| return self.post('friendships/update', params=params) | |
| def show_friendship(self, **params): | |
| """Returns detailed information about the relationship between two | |
| arbitrary users. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show | |
| """ | |
| return self.get('friendships/show', params=params) | |
| def get_friends_list(self, **params): | |
| """Returns a cursored collection of user objects for every user the | |
| specified user is following (otherwise known as their "friends"). | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list | |
| """ | |
| return self.get('friends/list', params=params) | |
| get_friends_list.iter_mode = 'cursor' | |
| get_friends_list.iter_key = 'users' | |
| def get_followers_list(self, **params): | |
| """Returns a cursored collection of user objects for users | |
| following the specified user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list | |
| """ | |
| return self.get('followers/list', params=params) | |
| get_followers_list.iter_mode = 'cursor' | |
| get_followers_list.iter_key = 'users' | |
| # Users | |
| def get_account_settings(self, **params): | |
| """Returns settings (including current trend, geo and sleep time | |
| information) for the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-settings | |
| """ | |
| return self.get('account/settings', params=params) | |
| def verify_credentials(self, **params): | |
| """Returns an HTTP 200 OK response code and a representation of the | |
| requesting user if authentication was successful; returns a 401 status | |
| code and an error message if not. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials | |
| """ | |
| return self.get('account/verify_credentials', params=params) | |
| def update_account_settings(self, **params): | |
| """Updates the authenticating user's settings. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-settings | |
| """ | |
| return self.post('account/settings', params=params) | |
| def update_delivery_service(self, **params): | |
| """Sets which device Twitter delivers updates to for the authenticating user. | |
| Docs: | |
| https://dev.twitter.com/docs/api/1.1/post/account/update_delivery_device | |
| """ | |
| return self.post('account/update_delivery_device', params=params) | |
| def update_profile(self, **params): | |
| """Sets values that users are able to set under the "Account" tab of their | |
| settings page. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile | |
| """ | |
| return self.post('account/update_profile', params=params) | |
| def update_profile_banner_image(self, **params): # pragma: no cover | |
| """Updates the authenticating user's profile background image. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_background_image | |
| """ | |
| return self.post('account/update_profile_banner', params=params) | |
| def update_profile_colors(self, **params): # pragma: no cover | |
| """Sets one or more hex values that control the color scheme of the | |
| authenticating user's profile page on twitter.com. | |
| This method is deprecated, replaced by the ``profile_link_color`` | |
| parameter to :meth:`update_profile`. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile | |
| """ | |
| warnings.warn( | |
| 'This method is deprecated. You should use the' | |
| ' profile_link_color parameter in Twython.update_profile instead.', | |
| TwythonDeprecationWarning, | |
| stacklevel=2 | |
| ) | |
| return self.post('account/update_profile_colors', params=params) | |
| def update_profile_image(self, **params): # pragma: no cover | |
| """Updates the authenticating user's profile image. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image | |
| """ | |
| return self.post('account/update_profile_image', params=params) | |
| def list_blocks(self, **params): | |
| """Returns a collection of user objects that the authenticating user | |
| is blocking. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list | |
| """ | |
| return self.get('blocks/list', params=params) | |
| list_blocks.iter_mode = 'cursor' | |
| list_blocks.iter_key = 'users' | |
| def list_block_ids(self, **params): | |
| """Returns an array of numeric user ids the authenticating user is blocking. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids | |
| """ | |
| return self.get('blocks/ids', params=params) | |
| list_block_ids.iter_mode = 'cursor' | |
| list_block_ids.iter_key = 'ids' | |
| def create_block(self, **params): | |
| """Blocks the specified user from following the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create | |
| """ | |
| return self.post('blocks/create', params=params) | |
| def destroy_block(self, **params): | |
| """Un-blocks the user specified in the ``id`` parameter for the | |
| authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy | |
| """ | |
| return self.post('blocks/destroy', params=params) | |
| def lookup_user(self, **params): | |
| """Returns fully-hydrated user objects for up to 100 users per request, | |
| as specified by comma-separated values passed to the ``user_id`` and/or | |
| ``screen_name`` parameters. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup | |
| """ | |
| return self.get('users/lookup', params=params) | |
| def show_user(self, **params): | |
| """Returns a variety of information about the user specified by the | |
| required ``user_id`` or ``screen_name`` parameter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show | |
| """ | |
| return self.get('users/show', params=params) | |
| def search_users(self, **params): | |
| """Provides a simple, relevance-based search interface to public user | |
| accounts on Twitter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search | |
| """ | |
| return self.get('users/search', params=params) | |
| def get_contributees(self, **params): | |
| """Returns a collection of users that the specified user can "contribute" to. | |
| Docs: https://dev.twitter.com/docs/api/1.1/get/users/contributees | |
| """ | |
| return self.get('users/contributees', params=params) | |
| def get_contributors(self, **params): | |
| """Returns a collection of users who can contribute to the specified account. | |
| Docs: https://dev.twitter.com/docs/api/1.1/get/users/contributors | |
| """ | |
| return self.get('users/contributors', params=params) | |
| def remove_profile_banner(self, **params): | |
| """Removes the uploaded profile banner for the authenticating user. | |
| Returns HTTP 200 upon success. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner | |
| """ | |
| return self.post('account/remove_profile_banner', params=params) | |
| def update_profile_background_image(self, **params): | |
| """Uploads a profile banner on behalf of the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner | |
| """ | |
| return self.post('account/update_profile_background_image', | |
| params=params) | |
| def get_profile_banner_sizes(self, **params): | |
| """Returns a map of the available size variations of the specified | |
| user's profile banner. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner | |
| """ | |
| return self.get('users/profile_banner', params=params) | |
| def list_mutes(self, **params): | |
| """Returns a collection of user objects that the authenticating user | |
| is muting. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list | |
| """ | |
| return self.get('mutes/users/list', params=params) | |
| list_mutes.iter_mode = 'cursor' | |
| list_mutes.iter_key = 'users' | |
| def list_mute_ids(self, **params): | |
| """Returns an array of numeric user ids the authenticating user | |
| is muting. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids | |
| """ | |
| return self.get('mutes/users/ids', params=params) | |
| list_mute_ids.iter_mode = 'cursor' | |
| list_mute_ids.iter_key = 'ids' | |
| def create_mute(self, **params): | |
| """Mutes the specified user, preventing their tweets appearing | |
| in the authenticating user's timeline. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create | |
| """ | |
| return self.post('mutes/users/create', params=params) | |
| def destroy_mute(self, **params): | |
| """Un-mutes the user specified in the user or ``id`` parameter for | |
| the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy | |
| """ | |
| return self.post('mutes/users/destroy', params=params) | |
| # Suggested Users | |
| def get_user_suggestions_by_slug(self, **params): | |
| """Access the users in a given category of the Twitter suggested user list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug | |
| """ | |
| return self.get('users/suggestions/%s' % params.get('slug'), | |
| params=params) | |
| def get_user_suggestions(self, **params): | |
| """Access to Twitter's suggested user list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions | |
| """ | |
| return self.get('users/suggestions', params=params) | |
| def get_user_suggestions_statuses_by_slug(self, **params): | |
| """Access the users in a given category of the Twitter suggested user | |
| list and return their most recent status if they are not a protected | |
| user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug-members | |
| """ | |
| return self.get('users/suggestions/%s/members' % params.get('slug'), | |
| params=params) | |
| # Favorites | |
| def get_favorites(self, **params): | |
| """Returns the 20 most recent Tweets favorited by the authenticating | |
| or specified user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list | |
| """ | |
| return self.get('favorites/list', params=params) | |
| get_favorites.iter_mode = 'id' | |
| def destroy_favorite(self, **params): | |
| """Un-favorites the status specified in the ``id`` parameter as the | |
| authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-destroy | |
| """ | |
| return self.post('favorites/destroy', params=params) | |
| def create_favorite(self, **params): | |
| """Favorites the status specified in the ``id`` parameter as the | |
| authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-create | |
| """ | |
| return self.post('favorites/create', params=params) | |
| # Lists | |
| def show_lists(self, **params): | |
| """Returns all lists the authenticating or specified user subscribes to, | |
| including their own. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list | |
| """ | |
| return self.get('lists/list', params=params) | |
| def get_list_statuses(self, **params): | |
| """Returns a timeline of tweets authored by members of the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses | |
| """ | |
| return self.get('lists/statuses', params=params) | |
| get_list_statuses.iter_mode = 'id' | |
| def delete_list_member(self, **params): | |
| """Removes the specified member from the list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy | |
| """ | |
| return self.post('lists/members/destroy', params=params) | |
| def get_list_memberships(self, **params): | |
| """Returns the lists the specified user has been added to. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships | |
| """ | |
| return self.get('lists/memberships', params=params) | |
| get_list_memberships.iter_mode = 'cursor' | |
| get_list_memberships.iter_key = 'lists' | |
| def get_list_subscribers(self, **params): | |
| """Returns the subscribers of the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers | |
| """ | |
| return self.get('lists/subscribers', params=params) | |
| get_list_subscribers.iter_mode = 'cursor' | |
| get_list_subscribers.iter_key = 'users' | |
| def subscribe_to_list(self, **params): | |
| """Subscribes the authenticated user to the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create | |
| """ | |
| return self.post('lists/subscribers/create', params=params) | |
| def is_list_subscriber(self, **params): | |
| """Check if the specified user is a subscriber of the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show | |
| """ | |
| return self.get('lists/subscribers/show', params=params) | |
| def unsubscribe_from_list(self, **params): | |
| """Unsubscribes the authenticated user from the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy | |
| """ | |
| return self.post('lists/subscribers/destroy', params=params) | |
| def create_list_members(self, **params): | |
| """Adds multiple members to a list, by specifying a comma-separated | |
| list of member ids or screen names. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all | |
| """ | |
| return self.post('lists/members/create_all', params=params) | |
| def is_list_member(self, **params): | |
| """Check if the specified user is a member of the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show | |
| """ | |
| return self.get('lists/members/show', params=params) | |
| def get_list_members(self, **params): | |
| """Returns the members of the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members | |
| """ | |
| return self.get('lists/members', params=params) | |
| get_list_members.iter_mode = 'cursor' | |
| get_list_members.iter_key = 'users' | |
| def add_list_member(self, **params): | |
| """Add a member to a list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create | |
| """ | |
| return self.post('lists/members/create', params=params) | |
| def delete_list(self, **params): | |
| """Deletes the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy | |
| """ | |
| return self.post('lists/destroy', params=params) | |
| def update_list(self, **params): | |
| """Updates the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-update | |
| """ | |
| return self.post('lists/update', params=params) | |
| def create_list(self, **params): | |
| """Creates a new list for the authenticated user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-create | |
| """ | |
| return self.post('lists/create', params=params) | |
| def get_specific_list(self, **params): | |
| """Returns the specified list. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-show | |
| """ | |
| return self.get('lists/show', params=params) | |
| def get_list_subscriptions(self, **params): | |
| """Obtain a collection of the lists the specified user is subscribed to. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions | |
| """ | |
| return self.get('lists/subscriptions', params=params) | |
| get_list_subscriptions.iter_mode = 'cursor' | |
| get_list_subscriptions.iter_key = 'lists' | |
| def delete_list_members(self, **params): | |
| """Removes multiple members from a list, by specifying a | |
| comma-separated list of member ids or screen names. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all | |
| """ | |
| return self.post('lists/members/destroy_all', params=params) | |
| def show_owned_lists(self, **params): | |
| """Returns the lists owned by the specified Twitter user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships | |
| """ | |
| return self.get('lists/ownerships', params=params) | |
| show_owned_lists.iter_mode = 'cursor' | |
| show_owned_lists.iter_key = 'lists' | |
| # Saved Searches | |
| def get_saved_searches(self, **params): | |
| """Returns the authenticated user's saved search queries. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/search/api-reference/get-saved_searches-list | |
| """ | |
| return self.get('saved_searches/list', params=params) | |
| def show_saved_search(self, **params): | |
| """Retrieve the information for the saved search represented by the given ``id``. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/search/api-reference/get-saved_searches-show-id | |
| """ | |
| return self.get('saved_searches/show/%s' % params.get('id'), | |
| params=params) | |
| def create_saved_search(self, **params): | |
| """Create a new saved search for the authenticated user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create | |
| """ | |
| return self.post('saved_searches/create', params=params) | |
| def destroy_saved_search(self, **params): | |
| """Destroys a saved search for the authenticating user. | |
| Docs: | |
| https://developer.twitter.com/en/docs/tweets/search/api-reference/post-saved_searches-destroy-id | |
| """ | |
| return self.post('saved_searches/destroy/%s' % params.get('id'), | |
| params=params) | |
| # Places & Geo | |
| def get_geo_info(self, **params): | |
| """Returns all the information about a known place. | |
| Docs: | |
| https://developer.twitter.com/en/docs/geo/place-information/api-reference/get-geo-id-place_id | |
| """ | |
| return self.get('geo/id/%s' % params.get('place_id'), params=params) | |
| def reverse_geocode(self, **params): | |
| """Given a latitude and a longitude, searches for up to 20 places | |
| that can be used as a place_id when updating a status. | |
| Docs: | |
| https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode | |
| """ | |
| return self.get('geo/reverse_geocode', params=params) | |
| def search_geo(self, **params): | |
| """Search for places that can be attached to a statuses/update. | |
| Docs: | |
| https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-search | |
| """ | |
| return self.get('geo/search', params=params) | |
| def get_similar_places(self, **params): | |
| """Locates places near the given coordinates which are similar in name. | |
| Docs: https://dev.twitter.com/docs/api/1.1/get/geo/similar_places | |
| """ | |
| return self.get('geo/similar_places', params=params) | |
| def create_place(self, **params): # pragma: no cover | |
| """Creates a new place object at the given latitude and longitude. | |
| Docs: https://dev.twitter.com/docs/api/1.1/post/geo/place | |
| """ | |
| return self.post('geo/place', params=params) | |
| # Trends | |
| def get_place_trends(self, **params): | |
| """Returns the top 10 trending topics for a specific WOEID, if | |
| trending information is available for it. | |
| Docs: | |
| https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place | |
| """ | |
| return self.get('trends/place', params=params) | |
| def get_available_trends(self, **params): | |
| """Returns the locations that Twitter has trending topic information for. | |
| Docs: | |
| https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available | |
| """ | |
| return self.get('trends/available', params=params) | |
| def get_closest_trends(self, **params): | |
| """Returns the locations that Twitter has trending topic information | |
| for, closest to a specified location. | |
| Docs: | |
| https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest | |
| """ | |
| return self.get('trends/closest', params=params) | |
| # Spam Reporting | |
| def report_spam(self, **params): # pragma: no cover | |
| """Report the specified user as a spam account to Twitter. | |
| Docs: | |
| https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam | |
| """ | |
| return self.post('users/report_spam', params=params) | |
| # OAuth | |
| def invalidate_token(self, **params): # pragma: no cover | |
| """Allows a registered application to revoke an issued OAuth 2 Bearer | |
| Token by presenting its client credentials. | |
| Docs: | |
| https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_token | |
| """ | |
| return self.post('oauth2/invalidate_token', params=params) | |
| # Help | |
| def get_twitter_configuration(self, **params): | |
| """Returns the current configuration used by Twitter | |
| Docs: | |
| https://developer.twitter.com/en/docs/developer-utilities/configuration/api-reference/get-help-configuration | |
| """ | |
| return self.get('help/configuration', params=params) | |
| def get_supported_languages(self, **params): | |
| """Returns the list of languages supported by Twitter along with | |
| their ISO 639-1 code. | |
| Docs: | |
| https://developer.twitter.com/en/docs/developer-utilities/supported-languages/api-reference/get-help-languages | |
| """ | |
| return self.get('help/languages', params=params) | |
| def get_privacy_policy(self, **params): | |
| """Returns Twitter's Privacy Policy | |
| Docs: | |
| https://developer.twitter.com/en/docs/developer-utilities/privacy-policy/api-reference/get-help-privacy | |
| """ | |
| return self.get('help/privacy', params=params) | |
| def get_tos(self, **params): | |
| """Return the Twitter Terms of Service | |
| Docs: | |
| https://developer.twitter.com/en/docs/developer-utilities/terms-of-service/api-reference/get-help-tos | |
| """ | |
| return self.get('help/tos', params=params) | |
| def get_application_rate_limit_status(self, **params): | |
| """Returns the current rate limits for methods belonging to the | |
| specified resource families. | |
| Docs: | |
| https://developer.twitter.com/en/docs/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status | |
| """ | |
| return self.get('application/rate_limit_status', params=params) | |
| # from https://developer.twitter.com/en/docs/ads/general/guides/response-codes | |
| TWITTER_HTTP_STATUS_CODE = { | |
| 200: ('OK', 'Success!'), | |
| 304: ('Not Modified', 'There was no new data to return.'), | |
| 400: ('Bad Request', 'The request was invalid. An accompanying \ | |
| error message will explain why. This is the status code \ | |
| will be returned during rate limiting.'), | |
| 401: ('Unauthorized', 'Authentication credentials were missing \ | |
| or incorrect.'), | |
| 403: ('Forbidden', 'The request is understood, but it has been \ | |
| refused. An accompanying error message will explain why. \ | |
| This code is used when requests are being denied due to \ | |
| update limits.'), | |
| 404: ('Not Found', 'The URI requested is invalid or the resource \ | |
| requested, such as a user, does not exists.'), | |
| 406: ('Not Acceptable', 'Returned by the Search API when an \ | |
| invalid format is specified in the request.'), | |
| 410: ('Gone', 'This resource is gone. Used to indicate that an \ | |
| API endpoint has been turned off.'), | |
| 422: ('Unprocessable Entity', 'Returned when an image uploaded to \ | |
| POST account/update_profile_banner is unable to be processed.'), | |
| 429: ('Too Many Requests', 'Returned in API v1.1 when a request cannot \ | |
| be served due to the application\'s rate limit having been \ | |
| exhausted for the resource.'), | |
| 500: ('Internal Server Error', 'Something is broken. Please post to the \ | |
| group so the Twitter team can investigate.'), | |
| 502: ('Bad Gateway', 'Twitter is down or being upgraded.'), | |
| 503: ('Service Unavailable', 'The Twitter servers are up, but overloaded \ | |
| with requests. Try again later.'), | |
| 504: ('Gateway Timeout', 'The Twitter servers are up, but the request \ | |
| couldn\'t be serviced due to some failure within our stack. Try \ | |
| again later.'), | |
| } |