Developer Interface

This page of the documentation will cover all methods and classes available to the developer.

Twython, currently, has two main interfaces:

• Twitter’s Core API (updating statuses, getting timelines, direct messaging, etc)
• Twitter’s Streaming API

Core Interface

class twython.Twython(app_key=None, app_secret=None, oauth_token=None, oauth_token_secret=None, headers=None, proxies=None, api_version='1.1', ssl_verify=True)

__init__(app_key=None, app_secret=None, oauth_token=None, oauth_token_secret=None, headers=None, proxies=None, api_version='1.1', ssl_verify=True)

Instantiates an instance of Twython. Takes optional parameters for authentication and such (see below).

Parameters:

• app_key – (optional) Your applications key
• app_secret – (optional) Your applications secret key
• oauth_token – (optional) Used with oauth_token_secret to make authenticated calls
• oauth_token_secret – (optional) Used with oauth_token to make authenticated calls
• headers – (optional) Custom headers to send along with the request
• proxies – (optional) A dictionary of proxies, for example {“http”:”proxy.example.org:8080”, “https”:”proxy.example.org:8081”}.
• ssl_verify – (optional) Turns off ssl verification when False. Useful if you have development server issues.

add_list_member(**params)

Add a member to a list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/create

static construct_api_url(api_url, **params)

Construct a Twitter API url, encoded, with parameters

Parameters:

• api_url – URL of the Twitter API endpoint you are attempting to construct
• **params – Parameters that are accepted by Twitter for the endpoint you’re requesting

Return type:

string

Usage:

>>> from twython import Twython
>>> twitter = Twython()

>>> api_url = 'https://api.twitter.com/1.1/search/tweets.json'
>>> constructed_url = twitter.construct_api_url(api_url, q='python', result_type='popular')
>>> print constructed_url
https://api.twitter.com/1.1/search/tweets.json?q=python&result_type=popular

create_block(**params)

Blocks the specified user from following the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/blocks/create

create_favorite(**params)

Favorites the status specified in the ID parameter as the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/favorites/create

create_friendship(**params)

Allows the authenticating users to follow the user specified in the ID parameter.

Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/create

create_list(**params)

Creates a new list for the authenticated user.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/create

create_list_members(**params)

Adds multiple members to a list, by specifying a comma-separated list of member ids or screen names.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all

create_place(**params)

Creates a new place object at the given latitude and longitude.

Docs: https://dev.twitter.com/docs/api/1.1/post/geo/place

create_saved_search(**params)

Create a new saved search for the authenticated user.

Docs: https://dev.twitter.com/docs/api/1.1/post/saved_searches/create

delete_list(**params)

Deletes the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/destroy

delete_list_member(**params)

Removes the specified member from the list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy

delete_list_members(**params)

Removes multiple members from a list, by specifying a comma-separated list of member ids or screen names.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy_all

destroy_block(**params)

Un-blocks the user specified in the ID parameter for the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/blocks/destroy

destroy_direct_message(**params)

Destroys the direct message specified in the required id parameter

Docs: https://dev.twitter.com/docs/api/1.1/post/direct_messages/destroy

destroy_favorite(**params)

Un-favorites the status specified in the ID parameter as the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/favorites/destroy

destroy_friendship(**params)

Allows the authenticating user to unfollow the user specified in the ID parameter.

Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/destroy

destroy_saved_search(**params)

Destroys a saved search for the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/saved_searches/destroy/%3Aid

destroy_status(**params)

Destroys the status specified by the required ID parameter

Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/destroy/%3Aid

get(endpoint, params=None, version='1.1')

Shortcut for GET requests via request

get_account_settings(**params)

Returns settings (including current trend, geo and sleep time information) for the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/get/account/settings

get_authentication_tokens(callback_url=None, force_login=False, screen_name='')

Returns a dict including an authorization URL, auth_url, to direct a user to

Parameters:

• callback_url – (optional) Url the user is returned to after they authorize your app (web clients only)
• force_login – (optional) Forces the user to enter their credentials to ensure the correct users account is authorized.
• app_secret – (optional) If forced_login is set OR user is not currently logged in, Prefills the username input box of the OAuth login screen with the given value

Return type:

dict

get_authorized_tokens(oauth_verifier)

Returns a dict of authorized tokens after they go through the get_authentication_tokens phase.

Parameters:oauth_verifier – (required) The oauth_verifier (or a.k.a PIN for non web apps) retrieved from the callback url querystring Return type:dict

get_available_trends(**params)

Returns the locations that Twitter has trending topic information for.

Docs: https://dev.twitter.com/docs/api/1.1/get/trends/available

get_closest_trends(**params)

Returns the locations that Twitter has trending topic information for, closest to a specified location.

Docs: https://dev.twitter.com/docs/api/1.1/get/trends/closest

get_contributees(**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

get_contributors(**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

get_direct_message(**params)

Returns a single direct message, specified by an id parameter.

Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages/show

get_direct_messages(**params)

Returns the 20 most recent direct messages sent to the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages

get_favorites(**params)

Returns the 20 most recent Tweets favorited by the authenticating or specified user.

Docs: https://dev.twitter.com/docs/api/1.1/get/favorites/list

get_followers_ids(**params)

Returns a cursored collection of user IDs for every user following the specified user.

Docs: https://dev.twitter.com/docs/api/1.1/get/followers/ids

get_followers_list(**params)

Returns a cursored collection of user objects for users following the specified user.

Docs: https://dev.twitter.com/docs/api/1.1/get/followers/list

get_friends_ids(**params)

Returns a cursored collection of user IDs for every user the specified user is following (otherwise known as their “friends”).

Docs: https://dev.twitter.com/docs/api/1.1/get/friends/ids

get_friends_list(**params)

Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their “friends”).

Docs: https://dev.twitter.com/docs/api/1.1/get/friends/list

get_geo_info(**params)

Returns all the information about a known place.

Docs: https://dev.twitter.com/docs/api/1.1/get/geo/id/%3Aplace_id

get_home_timline(**params)

Returns a collection of the most recent Tweets and retweets posted by the authenticating user and the users they follow.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline

get_incoming_friendship_ids(**params)

Returns a collection of numeric IDs for every user who has a pending request to follow the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/incoming

get_lastfunction_header(header)

Returns a specific header from the last API call This will return None if the header is not present

Parameters:header – (required) The name of the header you want to get the value of

Most useful for the following header information:

x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-class, x-rate-limit-reset

get_list_members(**params)

Returns the members of the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/members

get_list_statuses(**params)

Returns a timeline of tweets authored by members of the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/statuses

get_list_subscribers(**params)

Returns the subscribers of the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscribers

get_list_subscriptions(**params)

Obtain a collection of the lists the specified user is subscribed to.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscriptions

get_mentions_timeline(**params)

Returns the 20 most recent mentions (tweets containing a users’s @screen_name) for the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/mentions_timeline

get_oembed_tweet(**params)

Returns information allowing the creation of an embedded representation of a Tweet on third party sites.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/oembed

get_outgoing_friendship_ids(**params)

Returns a collection of numeric IDs for every protected user for whom the authenticating user has a pending follow request.

Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/outgoing

get_place_trends(**params)

Returns the top 10 trending topics for a specific WOEID, if trending information is available for it.

Docs: https://dev.twitter.com/docs/api/1.1/get/trends/place

get_profile_banner_sizes(**params)

Returns a map of the available size variations of the specified user’s profile banner.

Docs: https://dev.twitter.com/docs/api/1.1/get/users/profile_banner

get_retweeters_id(**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://dev.twitter.com/docs/api/1.1/get/statuses/retweeters/ids

get_retweets(**params)

Returns up to 100 of the first retweets of a given tweet.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/retweets/%3Aid

get_saved_searches(**params)

Returns the authenticated user’s saved search queries.

Docs: https://dev.twitter.com/docs/api/1.1/get/saved_searches/list

get_sent_messages(**params)

Returns the 20 most recent direct messages sent by the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages/sent

get_similar_places(**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

get_specific_list(**params)

Returns the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/show

get_user_ids_of_blocked_retweets(**params)

Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from.

Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/no_retweets/ids

get_user_suggestions(**params)

Access to Twitter’s suggested user list.

Docs: https://dev.twitter.com/docs/api/1.1/get/users/suggestions

get_user_suggestions_by_slug(**params)

Access the users in a given category of the Twitter suggested user list.

Docs: https://dev.twitter.com/docs/api/1.1/get/users/suggestions/%3Aslug

get_user_suggestions_statuses_by_slug(**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://dev.twitter.com/docs/api/1.1/get/users/suggestions/%3Aslug/members

get_user_timeline(**params)

Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/user_timeline

is_list_member(**params)

Check if the specified user is a member of the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/members/show

is_list_subscriber(**params)

Check if the specified user is a subscriber of the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscribers/show

list_block_ids(**params)

Returns an array of numeric user ids the authenticating user is blocking.

Docs: https://dev.twitter.com/docs/api/1.1/get/blocks/ids

list_blocks(**params)

Returns a collection of user objects that the authenticating user is blocking.

Docs: https://dev.twitter.com/docs/api/1.1/get/blocks/list

lookup_friendships(**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://dev.twitter.com/docs/api/1.1/get/friendships/lookup

lookup_user(**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://dev.twitter.com/docs/api/1.1/get/users/lookup

post(endpoint, params=None, version='1.1')

Shortcut for POST requests via request

remove_profile_banner(**params)

Removes the uploaded profile banner for the authenticating user. Returns HTTP 200 upon success.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/remove_profile_banner

report_spam(**params)

Report the specified user as a spam account to Twitter.

Docs: https://dev.twitter.com/docs/api/1.1/post/users/report_spam

request(endpoint, method='GET', params=None, version='1.1')

Return dict of response received from Twitter’s API

Parameters:

• endpoint (string) – (required) Full url or Twitter API endpoint (e.g. search/tweets)
• method (string) – (optional) Method of accessing data, either GET or POST. (default GET)
• params (dict or None) – (optional) Dict of parameters (if any) accepted the by Twitter API endpoint you are trying to access (default None)
• version (string) – (optional) Twitter API version to access (default 1.1)

Return type:

dict

retweet(**params)

Retweets a tweet specified by the id parameter

Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/retweet/%3Aid

retweeted_of_me(**params)

Returns the most recent tweets authored by the authenticating user that have been retweeted by others.

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/retweets_of_me

reverse_geocode(**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://dev.twitter.com/docs/api/1.1/get/geo/reverse_geocode

search(**params)

Returns a collection of relevant Tweets matching a specified query.

Docs: https://dev.twitter.com/docs/api/1.1/get/search/tweets

search_gen(search_query, **params)

Returns a generator of tweets that match a specified query.

Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets

Parameters:

• search_query – Query you intend to search Twitter for
• **params – Extra parameters to send with your search request

Return type:

generator

Usage:

>>> from twython import Twython
>>> twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET)

>>> search = twitter.search_gen('python')
>>> for result in search:
>>>   print result

search_geo(**params)

Search for places that can be attached to a statuses/update.

Docs: https://dev.twitter.com/docs/api/1.1/get/geo/search

search_users(**params)

Provides a simple, relevance-based search interface to public user accounts on Twitter.

Docs: https://dev.twitter.com/docs/api/1.1/get/users/search

send_direct_message(**params)

Sends a new direct message to the specified user from the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/direct_messages/new

show_friendship(**params)

Returns detailed information about the relationship between two arbitrary users.

Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/show

show_lists(**params)

Returns all lists the authenticating or specified user subscribes to, including their own.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/list

show_owned_lists(**params)

Returns the lists owned by the specified Twitter user.

Docs: https://dev.twitter.com/docs/api/1.1/get/lists/ownerships

show_saved_search(**params)

Retrieve the information for the saved search represented by the given id.

Docs: https://dev.twitter.com/docs/api/1.1/get/saved_searches/show/%3Aid

show_status(**params)

Returns a single Tweet, specified by the id parameter

Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/show/%3Aid

show_user(**params)

Returns a variety of information about the user specified by the required user_id or screen_name parameter.

Docs: https://dev.twitter.com/docs/api/1.1/get/users/show

subscribe_to_list(**params)

Subscribes the authenticated user to the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/create

unsubscribe_from_list(**params)

Unsubscribes the authenticated user from the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/destroy

update_account_settings(**params)

Updates the authenticating user’s settings.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/settings

update_delivery_service(**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

update_friendship(**params)

Allows one to enable or disable retweets and device notifications from the specified user.

Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/update

update_list(**params)

Updates the specified list.

Docs: https://dev.twitter.com/docs/api/1.1/post/lists/update

update_profile(**params)

Sets values that users are able to set under the “Account” tab of their settings page.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile

update_profile_Background_image(**params)

Uploads a profile banner on behalf of the authenticating user.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_banner

update_profile_background_image(**params)

Updates the authenticating user’s profile background image.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_background_image

update_profile_colors(**params)

Sets one or more hex values that control the color scheme of the authenticating user’s profile page on twitter.com.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_colors

update_profile_image(**params)

Updates the authenticating user’s profile image.

Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_image

update_status(**params)

Updates the authenticating user’s current status, also known as tweeting

Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/update

update_status_with_media(**params)

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://dev.twitter.com/docs/api/1.1/post/statuses/update_with_media

verify_Credentials(**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://dev.twitter.com/docs/api/1.1/get/account/verify_credentials

Streaming Interface

class twython.TwythonStreamer(app_key, app_secret, oauth_token, oauth_token_secret, timeout=300, retry_count=None, retry_in=10, headers=None)

__init__(app_key, app_secret, oauth_token, oauth_token_secret, timeout=300, retry_count=None, retry_in=10, headers=None)

Streaming class for a friendly streaming user experience Authentication IS required to use the Twitter Streaming API

Parameters:

• app_key – (required) Your applications key
• app_secret – (required) Your applications secret key
• oauth_token – (required) Used with oauth_token_secret to make authenticated calls
• oauth_token_secret – (required) Used with oauth_token to make authenticated calls
• timeout – (optional) How long (in secs) the streamer should wait for a response from Twitter Streaming API
• retry_count – (optional) Number of times the API call should be retired
• retry_in – (optional) Amount of time (in secs) the previous API call should be tried again
• headers – (optional) Custom headers to send along with the request

disconnect()

Used to disconnect the streaming client manually

on_delete(data)

Called when a deletion notice is received

Feel free to override this to handle your streaming data how you want it handled.

Twitter docs for deletion notices: http://spen.se/8qujd

Parameters:data (dict) – data from the ‘delete’ key recieved from the stream

on_disconnect(data)

Called when a disconnect notice is received

Feel free to override this to handle your streaming data how you want it handled.

Twitter docs for disconnect notices: http://spen.se/xb6mm

Parameters:data (dict) – data from the ‘disconnect’ key recieved from the stream

on_error(status_code, data)

Called when stream returns non-200 status code

Feel free to override this to handle your streaming data how you want it handled.

Parameters:

• status_code (int) – Non-200 status code sent from stream
• data (dict) – Error message sent from stream

on_limit(data)

Called when a limit notice is received

Feel free to override this to handle your streaming data how you want it handled.

Twitter docs for limit notices: http://spen.se/hzt0b

Parameters:data (dict) – data from the ‘limit’ key recieved from the stream

on_success(data)

Called when data has been successfull received from the stream

Feel free to override this to handle your streaming data how you want it handled. See https://dev.twitter.com/docs/streaming-apis/messages for messages sent along in stream responses.

Parameters:data (dict) – data recieved from the stream

on_timeout()

Called when the request has timed out

Streaming Types

class twython.streaming.types.TwythonStreamerTypes(streamer)

Class for different stream endpoints

Not all streaming endpoints have nested endpoints. User Streams and Site Streams are single streams with no nested endpoints Status Streams include filter, sample and firehose endpoints

site(**params)

Stream site

Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/site

user(**params)

Stream user

Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/user

class twython.streaming.types.TwythonStreamerTypesStatuses(streamer)

Class for different statuses endpoints

Available so TwythonStreamer.statuses.filter() is available. Just a bit cleaner than TwythonStreamer.statuses_filter(), statuses_sample(), etc. all being single methods in TwythonStreamer

filter(**params)

Stream statuses/filter

Parameters:**params – Paramters to send with your stream request

Accepted params found at: https://dev.twitter.com/docs/api/1.1/post/statuses/filter

firehose(**params)

Stream statuses/firehose

Parameters:**params – Paramters to send with your stream request

Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/statuses/firehose

sample(**params)

Stream statuses/sample

Parameters:**params – Paramters to send with your stream request

Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/statuses/sample

Exceptions

exception twython.TwythonError(msg, error_code=None, retry_after=None)

Generic error class, catch-all for most Twython issues. Special cases are handled by TwythonAuthError & TwythonRateLimitError.

from twython import TwythonError, TwythonRateLimitError, TwythonAuthError

exception twython.TwythonAuthError(msg, error_code=None, retry_after=None)

Raised when you try to access a protected resource and it fails due to some issue with your authentication.

exception twython.TwythonRateLimitError(msg, error_code, retry_after=None)

Raised when you’ve hit a rate limit.

The amount of seconds to retry your request in will be appended to the message.