twitter (version 0.4) | index /home/dewitt/svn/python-twitter/twitter.py

`A library that provides a python interface to the Twitter API`

Modules
`` |  |
md5 os simplejson | tempfile time twitter | urllib urllib2 urlparse |

Classes
`` |  | __builtin__.object Api DirectMessage Status User exceptions.Exception TwitterError
class Api(__builtin__.object)
`` | `A python interface into the Twitter API By default, the Api caches results for 1 minute. Example usage: To create an instance of the twitter.Api class, with no authentication: >>> import twitter >>> api = twitter.Api() To fetch the most recently posted public twitter status messages: >>> statuses = api.GetPublicTimeline() >>> print [s.user.name for s in statuses] [u'DeWitt', u'Kesuke Miyagi', u'ev', u'Buzz Andersen', u'Biz Stone'] #... To fetch a single user's public status messages, where "user" is either a Twitter "short name" or their user id. >>> statuses = api.GetUserTimeline(user) >>> print [s.text for s in statuses] To use authentication, instantiate the twitter.Api class with a username and password: >>> api = twitter.Api(username='twitter user', password='twitter pass') To fetch your friends (after being authenticated): >>> users = api.GetFriends() >>> print [u.name for u in users] To post a twitter status message (after being authenticated): >>> status = api.PostUpdate('I love python-twitter!') >>> print status.text I love python-twitter! There are many other methods, including: >>> api.PostDirectMessage(user, text) >>> api.GetUser(user) >>> api.GetReplies() >>> api.GetUserTimeline(user) >>> api.GetStatus(id) >>> api.DestroyStatus(id) >>> api.GetFriendsTimeline(user) >>> api.GetFriends(user) >>> api.GetFollowers() >>> api.GetFeatured() >>> api.GetDirectMessages() >>> api.PostDirectMessage(user, text) >>> api.DestroyDirectMessage(id) >>> api.DestroyFriendship(user) >>> api.CreateFriendship(user)`
| Methods defined here: ClearCredentials(self) `Clear the username and password for this instance` CreateFriendship(self, user) `Befriends the user specified in the user parameter as the authenticating user. The twitter.Api instance must be authenticated. Args: The ID or screen name of the user to befriend. Returns: A twitter.User instance representing the befriended user.` DestroyDirectMessage(self, id) `Destroys the direct message specified in the required ID parameter. The twitter.Api instance must be authenticated, and the authenticating user must be the recipient of the specified direct message. Args: id: The id of the direct message to be destroyed Returns: A twitter.DirectMessage instance representing the message destroyed` DestroyFriendship(self, user) `Discontinues friendship with the user specified in the user parameter. The twitter.Api instance must be authenticated. Args: The ID or screen name of the user with whom to discontinue friendship. Returns: A twitter.User instance representing the discontinued friend.` DestroyStatus(self, id) `Destroys the status specified by the required ID parameter. The twitter.Api instance must be authenticated and thee authenticating user must be the author of the specified status. Args: id: The numerical ID of the status you're trying to destroy. Returns: A twitter.Status instance representing the destroyed status message` GetDirectMessages(self, since=None) `Returns a list of the direct messages sent to the authenticating user. The twitter.Api instance must be authenticated. Args: since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date. [optional] Returns: A sequence of twitter.DirectMessage instances` GetFeatured(self) `Fetch the sequence of twitter.User instances featured on twitter.com The twitter.Api instance must be authenticated. Returns: A sequence of twitter.User instances` GetFollowers(self) `Fetch the sequence of twitter.User instances, one for each follower The twitter.Api instance must be authenticated. Returns: A sequence of twitter.User instances, one for each follower` GetFriends(self, user=None) `Fetch the sequence of twitter.User instances, one for each friend. Args: user: the username or id of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [optional] The twitter.Api instance must be authenticated. Returns: A sequence of twitter.User instances, one for each friend` GetFriendsTimeline(self, user=None, since=None) `Fetch the sequence of twitter.Status messages for a user's friends The twitter.Api instance must be authenticated if the user is private. Args: user: Specifies the ID or screen name of the user for whom to return the friends_timeline. If unspecified, the username and password must be set in the twitter.Api instance. [optional] since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date. [optional] Returns: A sequence of twitter.Status instances, one for each message` GetPublicTimeline(self, since_id=None) `Fetch the sequnce of public twitter.Status message for all users. Args: since_id: Returns only public statuses with an ID greater than (that is, more recent than) the specified ID. [Optional] Returns: An sequence of twitter.Status instances, one for each message` GetReplies(self) `Get a sequence of status messages representing the 20 most recent replies (status updates prefixed with @username) to the authenticating user. Returns: A sequence of twitter.Status instances, one for each reply to the user.` GetStatus(self, id) `Returns a single status message. The twitter.Api instance must be authenticated if the status message is private. Args: id: The numerical ID of the status you're trying to retrieve. Returns: A twitter.Status instance representing that status message` GetUser(self, user) `Returns a single user. The twitter.Api instance must be authenticated. Args: user: The username or id of the user to retrieve. Returns: A twitter.User instance representing that user` GetUserTimeline(self, user=None, count=None, since=None) `Fetch the sequence of public twitter.Status messages for a single user. The twitter.Api instance must be authenticated if the user is private. Args: user: either the username (short_name) or id of the user to retrieve. If not specified, then the current authenticated user is used. [optional] count: the number of status messages to retrieve [optional] since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date. [optional] Returns: A sequence of twitter.Status instances, one for each message up to count` PostDirectMessage(self, user, text) `Post a twitter direct message from the authenticated user The twitter.Api instance must be authenticated. Args: user: The ID or screen name of the recipient user. text: The message text to be posted. Must be less than 140 characters. Returns: A twitter.DirectMessage instance representing the message posted` PostUpdate(self, text) `Post a twitter status message from the authenticated user. The twitter.Api instance must be authenticated. Args: text: The message text to be posted. Must be less than 140 characters. Returns: A twitter.Status instance representing the message posted` SetCache(self, cache) `Override the default cache. Set to None to prevent caching. Args: cache: an instance that supports the same API as the twitter._FileCache` SetCacheTimeout(self, cache_timeout) `Override the default cache timeout. Args: cache_timeout: time, in seconds, that responses should be reused.` SetCredentials(self, username, password) `Set the username and password for this instance Args: username: The twitter username. password: The twitter password.` SetUrllib(self, urllib) `Override the default urllib implementation. Args: urllib: an instance that supports the same API as the urllib2 module` SetUserAgent(self, user_agent) `Override the default user agent Args: user_agent: a string that should be send to the server as the User-agent` __init__(self, username=None, password=None, encoding='utf-8') `Instantiate a new twitter.Api object. Args: username: The username of the twitter account. [optional] password: The password for the twitter account. [optional] encoding: The string encoding being used. [optional, default 'utf-8']` Data descriptors defined here: __dict__ `dictionary for instance variables (if defined)` __weakref__ `list of weak references to the object (if defined)` Data and other attributes defined here: DEFAULT_CACHE_TIMEOUT = 60
class DirectMessage(__builtin__.object)
`` | `A class representing the DirectMessage structure used by the twitter API. The DirectMessage structure exposes the following properties: direct_message.id direct_message.created_at direct_message.created_at_in_seconds # read only direct_message.sender_id direct_message.sender_screen_name direct_message.recipient_id direct_message.recipient_screen_name direct_message.text`
| Methods defined here: AsDict(self) `A dict representation of this twitter.DirectMessage instance. The return value uses the same key names as the JSON representation. Return: A dict representing this twitter.DirectMessage instance` AsJsonString(self) `A JSON string representation of this twitter.DirectMessage instance. Returns: A JSON string representation of this twitter.DirectMessage instance` GetCreatedAt(self) `Get the time this direct message was posted. Returns: The time this direct message was posted` GetCreatedAtInSeconds(self) `Get the time this direct message was posted, in seconds since the epoch. Returns: The time this direct message was posted, in seconds since the epoch.` GetId(self) `Get the unique id of this direct message. Returns: The unique id of this direct message` GetRecipientId(self) `Get the unique recipient id of this direct message. Returns: The unique recipient id of this direct message` GetRecipientScreenName(self) `Get the unique recipient screen name of this direct message. Returns: The unique recipient screen name of this direct message` GetSenderId(self) `Get the unique sender id of this direct message. Returns: The unique sender id of this direct message` GetSenderScreenName(self) `Get the unique sender screen name of this direct message. Returns: The unique sender screen name of this direct message` GetText(self) `Get the text of this direct message. Returns: The text of this direct message.` SetCreatedAt(self, created_at) `Set the time this direct message was posted. Args: created_at: The time this direct message was created` SetId(self, id) `Set the unique id of this direct message. Args: id: The unique id of this direct message` SetRecipientId(self, recipient_id) `Set the unique recipient id of this direct message. Args: recipient id: The unique recipient id of this direct message` SetRecipientScreenName(self, recipient_screen_name) `Set the unique recipient screen name of this direct message. Args: recipient_screen_name: The unique recipient screen name of this direct message` SetSenderId(self, sender_id) `Set the unique sender id of this direct message. Args: sender id: The unique sender id of this direct message` SetSenderScreenName(self, sender_screen_name) `Set the unique sender screen name of this direct message. Args: sender_screen_name: The unique sender screen name of this direct message` SetText(self, text) `Set the text of this direct message. Args: text: The text of this direct message` __eq__(self, other) __init__(self, id=None, created_at=None, sender_id=None, sender_screen_name=None, recipient_id=None, recipient_screen_name=None, text=None) `An object to hold a Twitter direct message. This class is normally instantiated by the twitter.Api class and returned in a sequence. Note: Dates are posted in the form "Sat Jan 27 04:17:38 +0000 2007" Args: id: The unique id of this direct message created_at: The time this direct message was posted sender_id: The id of the twitter user that sent this message sender_screen_name: The name of the twitter user that sent this message recipient_id: The id of the twitter that received this message recipient_screen_name: The name of the twitter that received this message text: The text of this direct message` __ne__(self, other) __str__(self) `A string representation of this twitter.DirectMessage instance. The return value is the same as the JSON string representation. Returns: A string representation of this twitter.DirectMessage instance.` Static methods defined here: NewFromJsonDict(data) `Create a new instance based on a JSON dict. Args: data: A JSON dict, as converted from the JSON in the twitter API Returns: A twitter.DirectMessage instance` Data descriptors defined here: __dict__ `dictionary for instance variables (if defined)` __weakref__ `list of weak references to the object (if defined)` created_at `The time this direct message was posted.` created_at_in_seconds `The time this direct message was posted, in seconds since the epoch` id `The unique id of this direct message.` recipient_id `The unique recipient id of this direct message.` recipient_screen_name `The unique recipient screen name of this direct message.` sender_id `The unique sender id of this direct message.` sender_screen_name `The unique sender screen name of this direct message.` text `The text of this direct message`
class Status(__builtin__.object)
`` | `A class representing the Status structure used by the twitter API. The Status structure exposes the following properties: status.created_at status.created_at_in_seconds # read only status.id status.text status.relative_created_at # read only status.user`
| Methods defined here: AsDict(self) `A dict representation of this twitter.Status instance. The return value uses the same key names as the JSON representation. Return: A dict representing this twitter.Status instance` AsJsonString(self) `A JSON string representation of this twitter.Status instance. Returns: A JSON string representation of this twitter.Status instance` GetCreatedAt(self) `Get the time this status message was posted. Returns: The time this status message was posted` GetCreatedAtInSeconds(self) `Get the time this status message was posted, in seconds since the epoch. Returns: The time this status message was posted, in seconds since the epoch.` GetId(self) `Get the unique id of this status message. Returns: The unique id of this status message` GetNow(self) `Get the wallclock time for this status message. Used to calculate relative_created_at. Defaults to the time the object was instantiated. Returns: Whatever the status instance believes the current time to be, in seconds since the epoch.` GetRelativeCreatedAt(self) `Get a human redable string representing the posting time Returns: A human readable string representing the posting time` GetText(self) `Get the text of this status message. Returns: The text of this status message.` GetUser(self) `Get a twitter.User reprenting the entity posting this status message. Returns: A twitter.User reprenting the entity posting this status message` SetCreatedAt(self, created_at) `Set the time this status message was posted. Args: created_at: The time this status message was created` SetId(self, id) `Set the unique id of this status message. Args: id: The unique id of this status message` SetNow(self, now) `Set the wallclock time for this status message. Used to calculate relative_created_at. Defaults to the time the object was instantiated. Args: now: The wallclock time for this instance.` SetText(self, text) `Set the text of this status message. Args: text: The text of this status message` SetUser(self, user) `Set a twitter.User reprenting the entity posting this status message. Args: user: A twitter.User reprenting the entity posting this status message` __eq__(self, other) __init__(self, created_at=None, id=None, text=None, user=None, now=None) `An object to hold a Twitter status message. This class is normally instantiated by the twitter.Api class and returned in a sequence. Note: Dates are posted in the form "Sat Jan 27 04:17:38 +0000 2007" Args: created_at: The time this status message was posted id: The unique id of this status message text: The text of this status message relative_created_at: A human readable string representing the posting time user: A twitter.User instance representing the person posting the message now: The current time, if the client choses to set it. Defaults to the wall clock time.` __ne__(self, other) __str__(self) `A string representation of this twitter.Status instance. The return value is the same as the JSON string representation. Returns: A string representation of this twitter.Status instance.` Static methods defined here: NewFromJsonDict(data) `Create a new instance based on a JSON dict. Args: data: A JSON dict, as converted from the JSON in the twitter API Returns: A twitter.Status instance` Data descriptors defined here: __dict__ `dictionary for instance variables (if defined)` __weakref__ `list of weak references to the object (if defined)` created_at `The time this status message was posted.` created_at_in_seconds `The time this status message was posted, in seconds since the epoch` id `The unique id of this status message.` now `The wallclock time for this status instance.` relative_created_at `Get a human readable string representingthe posting time` text `The text of this status message` user `A twitter.User reprenting the entity posting this status message`
class TwitterError(exceptions.Exception)
`` | `Base class for Twitter errors`
| Methods inherited from exceptions.Exception: __getitem__(...) __init__(...) __str__(...)
class User(__builtin__.object)
`` | `A class representing the User structure used by the twitter API. The User structure exposes the following properties: user.id user.name user.screen_name user.location user.description user.profile_image_url user.url user.status`
| Methods defined here: AsDict(self) `A dict representation of this twitter.User instance. The return value uses the same key names as the JSON representation. Return: A dict representing this twitter.User instance` AsJsonString(self) `A JSON string representation of this twitter.User instance. Returns: A JSON string representation of this twitter.User instance` GetDescription(self) `Get the short text description of this user. Returns: The short text description of this user` GetId(self) `Get the unique id of this user. Returns: The unique id of this user` GetLocation(self) `Get the geographic location of this user. Returns: The geographic location of this user` GetName(self) `Get the real name of this user. Returns: The real name of this user` GetProfileImageUrl(self) `Get the url of the thumbnail of this user. Returns: The url of the thumbnail of this user` GetScreenName(self) `Get the short username of this user. Returns: The short username of this user` GetStatus(self) `Get the latest twitter.Status of this user. Returns: The latest twitter.Status of this user` GetUrl(self) `Get the homepage url of this user. Returns: The homepage url of this user` SetDescription(self, description) `Set the short text description of this user. Args: description: The short text description of this user` SetId(self, id) `Set the unique id of this user. Args: id: The unique id of this user.` SetLocation(self, location) `Set the geographic location of this user. Args: location: The geographic location of this user` SetName(self, name) `Set the real name of this user. Args: name: The real name of this user` SetProfileImageUrl(self, profile_image_url) `Set the url of the thumbnail of this user. Args: profile_image_url: The url of the thumbnail of this user` SetScreenName(self, screen_name) `Set the short username of this user. Args: screen_name: the short username of this user` SetStatus(self, status) `Set the latest twitter.Status of this user. Args: status: The latest twitter.Status of this user` SetUrl(self, url) `Set the homepage url of this user. Args: url: The homepage url of this user` __eq__(self, other) __init__(self, id=None, name=None, screen_name=None, location=None, description=None, profile_image_url=None, url=None, status=None) __ne__(self, other) __str__(self) `A string representation of this twitter.User instance. The return value is the same as the JSON string representation. Returns: A string representation of this twitter.User instance.` Static methods defined here: NewFromJsonDict(data) `Create a new instance based on a JSON dict. Args: data: A JSON dict, as converted from the JSON in the twitter API Returns: A twitter.User instance` Data descriptors defined here: __dict__ `dictionary for instance variables (if defined)` __weakref__ `list of weak references to the object (if defined)` description `The short text description of this user.` id `The unique id of this user.` location `The geographic location of this user.` name `The real name of this user.` profile_image_url `The url of the thumbnail of this user.` screen_name `The short username of this user.` status `The latest twitter.Status of this user.` url `The homepage url of this user.`

Data
`` |  | __author__ = 'dewitt@google.com' __version__ = '0.4'

Author
`` |  | dewitt@google.com