From: Josh Roesslein Date: Thu, 24 Sep 2009 16:58:00 +0000 (-0500) Subject: Added documentation to API methods in api.py. Other minor updates. X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=6fed324811bfbc5ef64ff9a64378540e201fe2b9;p=tweepy.git Added documentation to API methods in api.py. Other minor updates. + Added new parameters for statuses/update; lat & long + friends_ids() & followers_ids() parameter changed page -> cursor + search() added "locale" parameter --- diff --git a/CHANGES b/CHANGES index eb3d5ef..ee21514 100644 --- a/CHANGES +++ b/CHANGES @@ -10,6 +10,9 @@ during upgrade will be listed here. + Added Retweet Streaming method + New model: Retweet + Updated statuses parser to handle retweet_details + + Added new parameters for statuses/update; lat & long + + friends_ids() & followers_ids() parameter changed page -> cursor + + search() added "locale" parameter + OAuthHandler + Added set_request_token() method + Added support for "sign in with twitter". @@ -18,6 +21,7 @@ during upgrade will be listed here. See http://apiwiki.twitter.com/Sign-in-with-Twitter + Examples + Appengine demo (oauth) ++ Documentation of each method in api.py 1.0 -> 1.0.1 ============ diff --git a/tweepy/api.py b/tweepy/api.py index ee85694..8e0038b 100644 --- a/tweepy/api.py +++ b/tweepy/api.py @@ -36,14 +36,34 @@ class API(object): else: raise TweepError('Invalid auth type') - """Get public timeline""" + """ statuses/public_timeline + + Returns the 20 most recent statuses from non-protected users who + have set a custom user icon. The public timeline is cached for 60 + seconds so requesting it more often than that is a waste of resources. + + Parameters: None + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-public_timeline + """ public_timeline = bind_api( path = '/statuses/public_timeline.json', parser = parse_statuses, allowed_param = [] ) - """Get home timeline""" + """ statuses/home_timeline [Coming soon] + + Returns the 20 most recent statuses, including retweets, posted + by the authenticating user and that user's friends. This is the + equivalent of /timeline/home on the Web. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-home_timeline + """ home_timeline = bind_api( path = '/statuses/home_timeline.json', parser = parse_statuses, @@ -51,7 +71,16 @@ class API(object): require_auth = True ) - """Get friends timeline""" + """ statuses/friends_timeline + + Returns the 20 most recent statuses posted by the + authenticating user and that user's friends. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-friends_timeline + """ friends_timeline = bind_api( path = '/statuses/friends_timeline.json', parser = parse_statuses, @@ -59,7 +88,17 @@ class API(object): require_auth = True ) - """Get user timeline""" + """ statuses/user_timeline + + Returns the 20 most recent statuses posted from the + authenticating user. It's also possible to request another + user's timeline via the id parameter. + + Parameters: (id or user_id or screen_name), since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-user_timeline + """ user_timeline = bind_api( path = '/statuses/user_timeline.json', parser = parse_statuses, @@ -67,7 +106,16 @@ class API(object): 'max_id', 'count', 'page'] ) - """Get mentions""" + """ statuses/mentions + + Returns the 20 most recent mentions (status containing @username) + for the authenticating user. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-mentions + """ mentions = bind_api( path = '/statuses/mentions.json', parser = parse_statuses, @@ -75,7 +123,15 @@ class API(object): require_auth = True ) - """Get Retweets posted by user""" + """ statuses/retweeted_by_me [Coming soon] + + Returns the 20 most recent retweets posted by the authenticating user. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweeted_by_me + """ retweeted_by_me = bind_api( path = '/statuses/retweeted_by_me.json', parser = parse_statuses, @@ -83,7 +139,16 @@ class API(object): require_auth = True ) - """Get Retweets posted by user's friends""" + """ statuses/retweeted_to_me + + Returns the 20 most recent retweets posted by the + authenticating user's friends. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweeted_to_me + """ retweeted_to_me = bind_api( path = '/statuses/retweeted_to_me.json', parser = parse_statuses, @@ -91,7 +156,16 @@ class API(object): require_auth = True ) - """Get Retweets of the user's tweets posted by others""" + """ statuses/retweets_of_me + + Returns the 20 most recent tweets of the authenticated + user that have been retweeted by others. + + Parameters: since_id, max_id, count, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweets_of_me + """ retweets_of_me = bind_api( path = '/statuses/retweets_of_me.json', parser = parse_statuses, @@ -99,23 +173,49 @@ class API(object): require_auth = True ) - """Show status""" + """ statuses/show + + Returns a single status, specified by the id parameter below. + The status's author will be returned inline. + + Parameters: id (Required) + Returns: Status + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0show + """ get_status = bind_api( path = '/statuses/show.json', parser = parse_status, allowed_param = ['id'] ) - """Update status""" + """ statuses/update [Geolocation parameters coming soon] + + Updates the authenticating user's status. + A status update with text identical to the authenticating user's + current status will be ignored to prevent duplicates. + + Parameters: status (Required), in_reply_to_status_id, lat, long + Returns: Status + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0update + """ update_status = bind_api( path = '/statuses/update.json', method = 'POST', parser = parse_status, - allowed_param = ['status', 'in_reply_to_status_id'], + allowed_param = ['status', 'in_reply_to_status_id', 'lat', 'long'], require_auth = True ) - """Destroy status""" + """ statuses/destroy + + Destroys the status specified by the required ID parameter. + The authenticating user must be the author of the specified status. + + Parameters: id (Required) + Returns: Status + """ destroy_status = bind_api( path = '/statuses/destroy.json', method = 'DELETE', @@ -124,7 +224,16 @@ class API(object): require_auth = True ) - """Retweet a tweet""" + """ statuses/retweet [Coming soon] + + Retweets a tweet. Requires the id parameter of the tweet you are + retweeting. Returns the original tweet with retweet details. + + Parameters: id (Required) + Returns: Status + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweet + """ retweet = bind_api( path = '/statuses/retweet/id.json', method = 'POST', @@ -133,7 +242,15 @@ class API(object): require_auth = True ) - """Get the retweets of the specified tweet ID""" + """ statuses/retweets [Coming soon] + + Returns up to 100 of the first retweets of a given tweet. + + Parameters: id (Required), count + Returns: Retweet + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweets + """ def retweets(self, id, *args, **kargs): return bind_api( path = '/statuses/retweets/%s.json' % id, @@ -142,14 +259,31 @@ class API(object): require_auth = True )(self, *args, **kargs) - """Show user""" + """ users/show + + Returns extended information of a given user, specified by ID or + screen name as per the required id parameter. + + Parameters: id or user_id or screen_name (One of these is required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show + """ get_user = bind_api( path = '/users/show.json', parser = parse_user, allowed_param = ['id', 'user_id', 'screen_name'] ) - """Get authenticated user""" + """ Get the authenticated user + + Equivalent of calling API.get_user(authenticated_user_name) + + Parameters: None + Returns: User + + See: API.get_user() + """ def me(self): # if username not fetched, go get it... if self._username is None: @@ -168,14 +302,41 @@ class API(object): return self.get_user(screen_name=self._username) - """Show friends""" + """ statuses/friends + + Returns a user's friends. They are ordered by the order in + which they were added as friends, 100 at a time. + (Please note that the result set isn't guaranteed to be 100 + every time as suspended users will be filtered out.) + Use the page option to access older friends. With no user specified, + request defaults to the authenticated user's friends. It's also + possible to request another user's friends list via the id, + screen_name or user_id parameter. + + Parameters: (id or user_id or screen_name), page + Returns: list[Users] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0friends + """ friends = bind_api( path = '/statuses/friends.json', parser = parse_users, allowed_param = ['id', 'user_id', 'screen_name', 'page'] ) - """Show followers""" + """ statuses/followers + + Returns the authenticating user's followers.They are ordered by + the order in which they joined Twitter, 100 at a time. + (Please note that the result set isn't guaranteed to be 100 every + time as suspended users will be filtered out.) + Use the page option to access earlier followers. + + Parameters: (id or user_id or screen_name), page + Returns: list[User] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0followers + """ followers = bind_api( path = '/statuses/followers.json', parser = parse_users, @@ -183,7 +344,16 @@ class API(object): require_auth = True ) - """Get direct messages""" + """ direct_messages + + Returns a list of the 20 most recent direct messages sent + to the authenticating user. + + Parameters: since_id, max_id, count, page + Returns: list[DirectMessage] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-direct_messages + """ direct_messages = bind_api( path = '/direct_messages.json', parser = parse_directmessages, @@ -191,7 +361,16 @@ class API(object): require_auth = True ) - """Sent direct messages""" + """ direct_messages/sent + + Returns a list of the 20 most recent direct messages sent + by the authenticating user. + + Parameters: since_id, max_id, count, page + Returns: list[DirectMessage] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-direct_messages%C2%A0sent + """ sent_direct_messages = bind_api( path = '/direct_messages/sent.json', parser = parse_directmessages, @@ -199,7 +378,16 @@ class API(object): require_auth = True ) - """Send direct message""" + """ direct_messages/new + + Sends a new direct message to the specified user from + the authenticating user. + + Parameters: user (Required), text (Required) + Returns: DirectMessage + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-direct_messages%C2%A0new + """ send_direct_message = bind_api( path = '/direct_messages/new.json', method = 'POST', @@ -208,7 +396,17 @@ class API(object): require_auth = True ) - """Destroy direct message""" + """ direct_messages/destroy + + Destroys the direct message specified in the required ID parameter. + The authenticating user must be the recipient of the + specified direct message. + + Parameters: id (Required) + Returns: DirectMessage + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-direct_messages%C2%A0destroy + """ destroy_direct_message = bind_api( path = '/direct_messages/destroy.json', method = 'DELETE', @@ -217,7 +415,18 @@ class API(object): require_auth = True ) - """Create friendship""" + """ friendships/create + + Allows the authenticating users to follow the user specified in + the ID parameter. Returns the befriended user when successful. + + Parameters: + id or user_id or screen_name (One of these is required) + follow + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-friendships%C2%A0create + """ create_friendship = bind_api( path = '/friendships/create.json', method = 'POST', @@ -226,7 +435,16 @@ class API(object): require_auth = True ) - """Destroy friendship""" + """ friendships/destroy + + Allows the authenticating users to unfollow the user specified + in the ID parameter. Returns the unfollowed user when successful. + + Parameters: id or user_id or screen_name (One of these is required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-friendships%C2%A0destroy + """ destroy_friendship = bind_api( path = '/friendships/destroy.json', method = 'DELETE', @@ -235,14 +453,32 @@ class API(object): require_auth = True ) - """Check if friendship exists""" + """ friendships/exists + + Tests for the existence of friendship between two users. + + Parameters: user_a (Required), user_b (Required) + Returns: Boolean (True if user_a follows user_b, otherwise False) + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-friendships-exists + """ exists_friendship = bind_api( path = '/friendships/exists.json', parser = parse_json, allowed_param = ['user_a', 'user_b'] ) - """Show friendship details""" + """ friendships/show + + Returns detailed information about the relationship between two users. + + Parameters: + source_id or source_screen_name (One of these is required) + target_id or target_screen_name (One of these is required) + Returns: tuple(Friendship - source, Friendship - target) + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-friendships-show + """ show_friendship = bind_api( path = '/friendships/show.json', parser = parse_friendship, @@ -250,21 +486,54 @@ class API(object): 'target_id', 'target_screen_name'] ) - """Get list of IDs of users the specified user is following""" + """ friends/ids + + Returns an array of numeric IDs for every user the + specified user is following. + + Parameters: + id or user_id or screen_name (One of these is required) + cursor + Returns: json object + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-friends%C2%A0ids + """ friends_ids = bind_api( path = '/friends/ids.json', parser = parse_json, - allowed_param = ['id', 'user_id', 'screen_name', 'page'] + allowed_param = ['id', 'user_id', 'screen_name', 'cursor'] ) - """Get list of IDs of users following the specified user""" + """ followers/ids + + Returns an array of numeric IDs for every user following + the specified user. + + Parameters: + id or user_id or screen_name (One of these is required) + cursor + Returns: json object + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-followers%C2%A0ids + """ followers_ids = bind_api( path = '/followers/ids.json', parser = parse_json, - allowed_param = ['id', 'user_id', 'screen_name', 'page'] + allowed_param = ['id', 'user_id', 'screen_name', 'cursor'] ) - """Verify credentials""" + """ account/verify_credentials + + Use this method to test if supplied user credentials are valid. + Because this method can be a vector for a brute force dictionary + attack to determine a user's password, it is limited to 15 requests + per 60 minute period (starting from your first request). + + Parameters: None + Returns: True if credentials are valid, otherwise False + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0verify_credentials + """ def verify_credentials(self): try: return bind_api( @@ -275,13 +544,36 @@ class API(object): except TweepError: return False - """Rate limit status""" + """ account/rate_limit_status + + Returns the remaining number of API requests available to the + requesting user before the API limit is reached for the current hour. + Calls to rate_limit_status do not count against the rate limit. + If authentication credentials are provided, the rate limit status for + the authenticating user is returned. Otherwise, the rate limit status + for the requester's IP address is returned. + + Parameters: None + Returns: json object + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0rate_limit_status + """ rate_limit_status = bind_api( path = '/account/rate_limit_status.json', parser = parse_json ) - """Update delivery device""" + """ account/update_delivery_device + + Sets which device Twitter delivers updates to for the authenticating + user. Sending "none" as the device parameter will disable IM or SMS + updates. + + Parameters: device (Required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0update_delivery_device + """ set_delivery_device = bind_api( path = '/account/update_delivery_device.json', method = 'POST', @@ -290,7 +582,18 @@ class API(object): require_auth = True ) - """Update profile colors""" + """ account/update_profile_colors + + Sets one or more hex values that control the color scheme of the + authenticating user's profile page on twitter.com. + + Parameters: profile_background_color, profile_text_color, + profile_link_color, profile_sidebar_fill_color, + profile_sidebar_border_color + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0update_profile_colors + """ update_profile_colors = bind_api( path = '/account/update_profile_colors.json', method = 'POST', @@ -301,7 +604,16 @@ class API(object): require_auth = True ) - """Update profile image""" + """ account/update_profile_image + + Updates the authenticating user's profile image. + + Parameters: + filename - local file path to image (Required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0update_profile_image + """ def update_profile_image(self, filename): headers, post_data = _pack_image(filename, 700) bind_api( @@ -311,7 +623,17 @@ class API(object): require_auth = True )(self, post_data=post_data, headers=headers) - """Update profile background image""" + """ account/update_profile_background_image + + Updates the authenticating user's profile background image. + + Parameters: + filename - local file path to image (Required) + tile + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0update_profile_background_image + """ def update_profile_background_image(self, filename, *args, **kargs): headers, post_data = _pack_image(filename, 800) bind_api( @@ -322,7 +644,16 @@ class API(object): require_auth = True )(self, post_data=post_data, headers=headers) - """Update profile""" + """ account/update_profile + + Sets values that users are able to set under the "Account" tab of + their settings page. Only the parameters specified will be updated. + + Parameters: name, email, url, location, description + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0update_profile + """ update_profile = bind_api( path = '/account/update_profile.json', method = 'POST', @@ -331,14 +662,32 @@ class API(object): require_auth = True ) - """Get favorites""" + """ favorites + + Returns the 20 most recent favorite statuses for the authenticating + user or user specified by the ID parameter. + + Parameters: id, page + Returns: list[Status] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-favorites + """ favorites = bind_api( path = '/favorites.json', parser = parse_statuses, allowed_param = ['id', 'page'] ) - """Create favorite""" + """ favorites/create + + Favorites the status specified in the ID parameter as the + authenticating user. Returns the favorite status when successful. + + Parameters: id (Required) + Returns: Status + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-favorites%C2%A0create + """ create_favorite = bind_api( path = '/favorites/create.json', method = 'POST', @@ -347,7 +696,16 @@ class API(object): require_auth = True ) - """Destroy favorite""" + """ favorites/destroy + + Un-favorites the status specified in the ID parameter as the + authenticating user. Returns the un-favorited status. + + Parameters: id (Required) + Returns: Status + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-favorites%C2%A0destroy + """ destroy_favorite = bind_api( path = '/favorites/destroy.json', method = 'DELETE', @@ -356,7 +714,16 @@ class API(object): require_auth = True ) - """Enable device notifications""" + """ notifications/follow + + Enables device notifications for updates from the specified user. + Returns the specified user when successful. + + Parameters: id or user_id or screen_name (One of these is required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-notifications%C2%A0follow + """ enable_notifications = bind_api( path = '/notifications/follow.json', method = 'POST', @@ -365,7 +732,16 @@ class API(object): require_auth = True ) - """Disable device notifications""" + """ notifications/leave + + Disables notifications for updates from the specified user to the + authenticating user. Returns the specified user when successful. + + Parameters: id or user_id or screen_name (One of these is required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-notifications%C2%A0leave + """ disable_notifications = bind_api( path = '/notifications/leave.json', method = 'POST', @@ -374,7 +750,17 @@ class API(object): require_auth = True ) - """Create a block""" + """ blocks/create + + Blocks the user specified in the ID parameter as the authenticating + user. Destroys a friendship to the blocked user if it exists. + Returns the blocked user when successful. + + Parameters: id (Required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-blocks%C2%A0create + """ create_block = bind_api( path = '/blocks/create.json', method = 'POST', @@ -383,7 +769,16 @@ class API(object): require_auth = True ) - """Destroy a block""" + """ blocks/destroy + + Un-blocks the user specified in the ID parameter for the + authenticating user. Returns the un-blocked user when successful. + + Parameters: id (Required) + Returns: User + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-blocks%C2%A0destroy + """ destroy_block = bind_api( path = '/blocks/destroy.json', method = 'DELETE', @@ -392,7 +787,15 @@ class API(object): require_auth = True ) - """Check if block exists""" + """ blocks/exists + + Checks if the authenticating user is blocking a target user. + + Parameters: id or user_id or screen_name (One of these is required) + Returns: Boolean (True if blocked, otherwise False) + + http://apiwiki.twitter.com/Twitter+REST+API+Method%3A-blocks-exists + """ def exists_block(self, **kargs): try: bind_api( @@ -406,7 +809,16 @@ class API(object): return True - """Get list of users that are blocked""" + """ blocks/blocking + + Returns an array of user objects that the authenticating + user is blocking. + + Parameters: page + Returns: list[User] + + http://apiwiki.twitter.com/Twitter+REST+API+Method%3A-blocks-blocking + """ blocks = bind_api( path = '/blocks/blocking.json', parser = parse_users, @@ -414,21 +826,47 @@ class API(object): require_auth = True ) - """Get list of ids of users that are blocked""" + """ blocks/blocking/ids + + Returns an array of numeric user ids the authenticating + user is blocking. + + Parameters: None + Returns: json object + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-blocks-blocking-ids + """ blocks_ids = bind_api( path = '/blocks/blocking/ids.json', parser = parse_json, require_auth = True ) - """Get list of saved searches""" + """ saved_searches + + Returns the authenticated user's saved search queries. + + Parameters: None + Returns: list[SavedSearch] + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-saved_searches + """ saved_searches = bind_api( path = '/saved_searches.json', parser = parse_saved_searches, require_auth = True ) - """Get a single saved search by id""" + """ saved_searches/show + + Retrieve the data for a saved search owned by the + authenticating user specified by the given id. + + Parameters: id (Required) + Returns: SavedSearch + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-saved_searches-show + """ def get_saved_search(self, id): return bind_api( path = '/saved_searches/show/%s.json' % id, @@ -436,7 +874,15 @@ class API(object): require_auth = True )(self) - """Create new saved search""" + """ saved_searches/create + + Creates a saved search for the authenticated user. + + Parameters: query (Required) + Returns: SavedSearch + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-saved_searches-create + """ create_saved_search = bind_api( path = '/saved_searches/create.json', method = 'POST', @@ -445,7 +891,16 @@ class API(object): require_auth = True ) - """Destroy a saved search""" + """ saved_searches/destroy + + Destroys a saved search for the authenticated user. + The search specified by id must be owned by the authenticating user. + + Parameters: id (Required) + Returns: SavedSearch + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-saved_searches-destroy + """ def destroy_saved_search(self, id): return bind_api( path = '/saved_searches/destroy/%s.json' % id, @@ -455,22 +910,54 @@ class API(object): require_auth = True )(self) + """ help/test + + Invokes the test method in the Twitter API. + + Parameters: None + Returns: Boolean (True if 200 status code returned, otherwise False) + + http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-help%C2%A0test + """ def test(self): - return bind_api( - path = '/help/test.json', - parser = parse_return_true - )(self) + try: + return bind_api( + path = '/help/test.json', + parser = parse_return_true + )(self) + except TweepError: + return False + + """ search - """Search API""" + Returns tweets that match a specified query. + + Parameters: q (Required), lang, locale, rpp, page, since_id + geocode, show_user + Returns: list[SearchResult] + + http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search + """ def search(self, *args, **kargs): return bind_api( host = 'search.' + self.host, path = '/search.json', parser = parse_search_results, - allowed_param = ['q', 'lang', 'rpp', 'page', 'since_id', 'geocode', 'show_user'], + allowed_param = ['q', 'lang', 'locale', 'rpp', 'page', 'since_id', 'geocode', 'show_user'], )(self, *args, **kargs) + """ trends + + Returns the top ten topics that are currently trending on Twitter. + The response includes the time of the request, the name of each trend, + and the url to the Twitter Search results page for that topic. + + Parameters: None + Returns: json object + + http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends + """ def trends(self): return bind_api( host = 'search.' + self.host, @@ -478,6 +965,18 @@ class API(object): parser = parse_json )(self) + """ trends/current + + Returns the current top 10 trending topics on Twitter. + The response includes the time of the request, the name of each + trending topic, and query used on Twitter Search results + page for that topic. + + Parameters: exclude + Returns: json object + + http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-current + """ def trends_current(self, *args, **kargs): return bind_api( host = 'search.' + self.host, @@ -486,6 +985,15 @@ class API(object): allowed_param = ['exclude'] )(self, *args, **kargs) + """ trends/daily + + Returns the top 20 trending topics for each hour in a given day. + + Parameters: date, exclude + Returns: json object + + http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-daily + """ def trends_daily(self, *args, **kargs): return bind_api( host = "search." + self.host, @@ -494,6 +1002,15 @@ class API(object): allowed_param = ['date', 'exclude'] )(self, *args, **kargs) + """ trends/weekly + + Returns the top 30 trending topics for each day in a given week. + + Parameters: date, exclude + Returns: json object + + http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-weekly + """ def trends_weekly(self, *args, **kargs): return bind_api( host = "search." + self.host, @@ -502,6 +1019,8 @@ class API(object): allowed_param = ['date', 'exclude'] )(self, *args, **kargs) + """ Internal use only """ + def _pack_image(filename, max_size): """Pack image from file into multipart-formdata post body""" # image must be less than 700kb in size