Fork me on GitHub Developer Interface — Twython 3.8.0 documentation
Open Table Of Contents

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, access_token=None, token_type='bearer', oauth_version=1, api_version='1.1', client_args=None, auth_endpoint='authenticate')
__init__(app_key=None, app_secret=None, oauth_token=None, oauth_token_secret=None, access_token=None, token_type='bearer', oauth_version=1, api_version='1.1', client_args=None, auth_endpoint='authenticate')

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) When using OAuth 1, combined with

oauth_token_secret to make authenticated calls :param oauth_token_secret: (optional) When using OAuth 1 combined with oauth_token to make authenticated calls :param access_token: (optional) When using OAuth 2, provide a valid access token if you have one :param token_type: (optional) When using OAuth 2, provide your token type. Default: bearer :param oauth_version: (optional) Choose which OAuth version to use. Default: 1 :param api_version: (optional) Choose which Twitter API version to use. Default: 1.1

Parameters:client_args – (optional) Accepts some requests Session parameters
and some requests Request parameters.
See http://docs.python-requests.org/en/latest/api/#sessionapi and requests section below it for details. [ex. headers, proxies, verify(SSL verification)]
Parameters:auth_endpoint – (optional) Lets you select which authentication
endpoint will use your application.

This will allow the application to have DM access if the endpoint is ‘authorize’.

Default: authenticate.
add_list_member(**params)

Add a member to a list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create

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 :param **params: Parameters that are accepted by Twitter for the endpoint you’re requesting :rtype: 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://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create

create_favorite(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-create

create_friendship(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create

create_list(**params)

Creates a new list for the authenticated user.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-create

create_list_members(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all

create_metadata(**params)

Adds metadata to a media element, such as image descriptions for visually impaired.

Docs: https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-metadata-create

create_mute(**params)

Mutes the specified user, preventing their tweets appearing in the authenticating user’s timeline.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create

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 a new saved search for the authenticated user.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create

cursor(function, return_pages=False, **params)

Returns a generator for results that match a specified query.

Parameters:function – Instance of a Twython function

(Twython.get_home_timeline, Twython.search) :param **params: Extra parameters to send with your request (usually parameters accepted by the Twitter API endpoint) :rtype: generator

Usage:

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

>>> results = twitter.cursor(twitter.search, q='python')
>>> for result in results:
>>>   print result
delete(endpoint, params=None, version='1.1', json_encoded=False)

Shortcut for delete requests via request

delete_list(**params)

Deletes the specified list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy

delete_list_member(**params)

Removes the specified member from the list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy

delete_list_members(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all

destroy_block(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy

destroy_direct_message(**params)

Destroys the direct message specified in the required id parameter

Docs: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event

destroy_favorite(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-destroy

destroy_friendship(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy

destroy_mute(**params)

Un-mutes the user specified in the user or id parameter for the authenticating user.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy

Destroys a saved search for the authenticating user.

Docs: https://developer.twitter.com/en/docs/tweets/search/api-reference/post-saved_searches-destroy-id

destroy_status(**params)

Destroys the status specified by the required id parameter

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id

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://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-settings

get_application_rate_limit_status(**params)

Returns the current rate limits for methods belonging to the specified resource families.

Docs: https://developer.twitter.com/en/docs/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status

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.
  • screen_name – (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 :rtype: dict

Returns the locations that Twitter has trending topic information for.

Docs: https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available

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

Docs: https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest

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://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event

get_direct_messages(**params)

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

Docs: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events

get_favorites(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list

get_followers_ids(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids

get_followers_list(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list

get_geo_info(**params)

Returns all the information about a known place.

Docs: https://developer.twitter.com/en/docs/geo/place-information/api-reference/get-geo-id-place_id

get_home_timeline(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming

get_lastfunction_header(header, default_return_value=None)

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://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members

get_list_memberships(**params)

Returns the lists the specified user has been added to.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships

get_list_statuses(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses

get_list_subscribers(**params)

Returns the subscribers of the specified list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers

get_list_subscriptions(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions

get_mentions_timeline(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline

get_oembed_tweet(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing

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

Docs: https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place

get_privacy_policy(**params)

Returns Twitter’s Privacy Policy

Docs: https://developer.twitter.com/en/docs/developer-utilities/privacy-policy/api-reference/get-help-privacy

get_profile_banner_sizes(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner

get_retweeters_ids(**params)

Returns a collection of up to 100 user IDs belonging to users who have retweeted the tweet specified by the id parameter.

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids

get_retweets(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id

get_saved_searches(**params)

Returns the authenticated user’s saved search queries.

Docs: https://developer.twitter.com/en/docs/tweets/search/api-reference/get-saved_searches-list

get_sent_messages(**params)

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

Docs: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message

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://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-show

get_supported_languages(**params)

Returns the list of languages supported by Twitter along with their ISO 639-1 code.

Docs: https://developer.twitter.com/en/docs/developer-utilities/supported-languages/api-reference/get-help-languages

get_tos(**params)

Return the Twitter Terms of Service

Docs: https://developer.twitter.com/en/docs/developer-utilities/terms-of-service/api-reference/get-help-tos

get_twitter_configuration(**params)

Returns the current configuration used by Twitter

Docs: https://developer.twitter.com/en/docs/developer-utilities/configuration/api-reference/get-help-configuration

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids

get_user_suggestions(**params)

Access to Twitter’s suggested user list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions

get_user_suggestions_by_slug(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug-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://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline

static html_for_tweet(tweet, use_display_url=True, use_expanded_url=False, expand_quoted_status=False)

Return HTML for a tweet (urls, mentions, hashtags, symbols replaced with links)

Parameters:
  • tweet – Tweet object from received from Twitter API
  • use_display_url – Use display URL to represent link

(ex. google.com, github.com). Default: True :param use_expanded_url: Use expanded URL to represent link (e.g. http://google.com). Default False

If use_expanded_url is True, it overrides use_display_url. If use_display_url and use_expanded_url is False, short url will be used (t.co/xxxxx)

invalidate_token(**params)

Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials.

Docs: https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_token

is_list_member(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show

is_list_subscriber(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show

list_block_ids(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids

list_blocks(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list

list_mute_ids(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids

list_mutes(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup

lookup_status(**params)

Returns fully-hydrated tweet objects for up to 100 tweets per request, as specified by comma-separated values passed to the id parameter.

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup

obtain_access_token()

Returns an OAuth 2 access token to make OAuth 2 authenticated read-only calls.

Return type:string
post(endpoint, params=None, version='1.1', json_encoded=False)

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://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner

report_spam(**params)

Report the specified user as a spam account to Twitter.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam

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

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, POST or DELETE. (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)
  • json_encoded (bool) – (optional) Flag to indicate if this method should send data encoded as json (default False)
Return type:

dict

retweet(**params)

Retweets a tweet specified by the id parameter

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id

retweeted_of_me(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me

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://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode

search(**params)

Returns a collection of relevant Tweets matching a specified query.

Docs: https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets

search_geo(**params)

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

Docs: https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-search

search_users(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search

send_direct_message(**params)

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

Docs: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event

show_friendship(**params)

Returns detailed information about the relationship between two arbitrary users.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show

show_lists(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list

show_owned_lists(**params)

Returns the lists owned by the specified Twitter user.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships

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

Docs: https://developer.twitter.com/en/docs/tweets/search/api-reference/get-saved_searches-show-id

show_status(**params)

Returns a single Tweet, specified by the id parameter

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id

show_user(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show

subscribe_to_list(**params)

Subscribes the authenticated user to the specified list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create

unsubscribe_from_list(**params)

Unsubscribes the authenticated user from the specified list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy

update_account_settings(**params)

Updates the authenticating user’s settings.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-settings

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://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update

update_list(**params)

Updates the specified list.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-update

update_profile(**params)

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

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile

update_profile_background_image(**params)

Uploads a profile banner on behalf of the authenticating user.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner

update_profile_banner_image(**params)

Updates the authenticating user’s profile background image.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_background_image

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.

This method is deprecated, replaced by the profile_link_color parameter to update_profile().

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile

update_profile_image(**params)

Updates the authenticating user’s profile image.

Docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image

update_status(**params)

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

Docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update

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://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update_with_media

upload_media(**params)

Uploads media file to Twitter servers. The file will be available to be attached to a status for 60 minutes. To attach to a update, pass a list of returned media ids to the update_status() method using the media_ids param.

Docs: https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload

upload_video(media, media_type, media_category=None, size=None, check_progress=False)

Uploads video file to Twitter servers in chunks. The file will be available to be attached to a status for 60 minutes. To attach to a update, pass a list of returned media ids to the update_status() method using the media_ids param.

Upload happens in 3 stages: - INIT call with size of media to be uploaded(in bytes). If this is more than 15mb, twitter will return error. - APPEND calls each with media chunk. This returns a 204(No Content) if chunk is received. - FINALIZE call to complete media upload. This returns media_id to be used with status update.

Twitter media upload api expects each chunk to be not more than 5mb. We are sending chunk of 1mb each.

Docs: https://developer.twitter.com/en/docs/media/upload-media/uploading-media/chunked-media-upload

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://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/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, client_args=None, handlers=None, chunk_size=1)
__init__(app_key, app_secret, oauth_token, oauth_token_secret, timeout=300, retry_count=None, retry_in=10, client_args=None, handlers=None, chunk_size=1)

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
  • client_args – (optional) Accepts some requests Session parameters and some requests Request parameters. See http://docs.python-requests.org/en/latest/api/#sessionapi and requests section below it for details. [ex. headers, proxies, verify(SSL verification)]
  • handlers – (optional) Array of message types for which corresponding handlers will be called
  • chunk_size – (optional) Define the buffer size before data is actually returned from the Streaming API. Default: 1
disconnect()

Used to disconnect the streaming client manually

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_success(data)

Called when data has been successfully received from the stream. Returns True if other handlers for this message should be invoked.

Feel free to override this to handle your streaming data how you want it handled. See https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/streaming-message-types 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

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.

dynamic_filter()

Stream statuses/filter with dynamic parameters

filter(**params)

Stream statuses/filter

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

Accepted params found at: https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter

firehose(**params)

Stream statuses/firehose

Parameters:**params – Parameters 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 – Parameters to send with your stream request

Accepted params found at: https://developer.twitter.com/en/docs/tweets/sample-realtime/api-reference/get-statuses-sample

set_dynamic_filter(**params)

Set/update statuses/filter

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

Accepted params found at: https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter

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.