Commit 6fed3248 authored by Josh Roesslein's avatar Josh Roesslein
Browse files

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
parent 696acd88
......@@ -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
============
......
......@@ -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