This page of the documentation will cover all methods and classes available to the developer.
Twython, currently, has two main interfaces:
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: |
|
---|
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 |
---|
Parameters: | auth_endpoint – (optional) Lets you select which authentication |
---|
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.
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.
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.
create_list
(**params)¶Creates a new list for the authenticated user.
create_list_members
(**params)¶Adds multiple members to a list, by specifying a comma-separated list of member ids or screen names.
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.
create_place
(**params)¶Creates a new place object at the given latitude and longitude.
create_saved_search
(**params)¶Create a new saved search for the authenticated user.
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.
delete_list_member
(**params)¶Removes the specified member from the list.
delete_list_members
(**params)¶Removes multiple members from a list, by specifying a comma-separated list of member ids or screen names.
destroy_block
(**params)¶Un-blocks the user specified in the id
parameter for the
authenticating user.
destroy_direct_message
(**params)¶Destroys the direct message specified in the required id
parameter
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.
destroy_mute
(**params)¶Un-mutes the user specified in the user or id
parameter for
the authenticating user.
destroy_saved_search
(**params)¶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_account_settings
(**params)¶Returns settings (including current trend, geo and sleep time information) for the authenticating user.
get_application_rate_limit_status
(**params)¶Returns the current rate limits for methods belonging to the specified resource families.
get_authentication_tokens
(callback_url=None, force_login=False, screen_name='')¶auth_url
, toParameters: |
|
---|---|
Return type: | dict |
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
get_available_trends
(**params)¶Returns the locations that Twitter has trending topic information for.
get_closest_trends
(**params)¶Returns the locations that Twitter has trending topic information for, closest to a specified location.
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.
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.
get_followers_list
(**params)¶Returns a cursored collection of user objects for users following the specified user.
get_friends_ids
(**params)¶Returns a cursored collection of user IDs for every user the specified user is following (otherwise known as their “friends”).
get_friends_list
(**params)¶Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their “friends”).
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.
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 |
---|
get_list_members
(**params)¶Returns the members of the specified list.
get_list_memberships
(**params)¶Returns the lists the specified user has been added to.
get_list_statuses
(**params)¶Returns a timeline of tweets authored by members of the specified list.
get_list_subscribers
(**params)¶Returns the subscribers of the specified list.
get_list_subscriptions
(**params)¶Obtain a collection of the lists the specified user is subscribed to.
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.
get_place_trends
(**params)¶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
Returns a map of the available size variations of the specified user’s 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.
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.
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.
get_supported_languages
(**params)¶Returns the list of languages supported by Twitter along with their ISO 639-1 code.
get_tos
(**params)¶Return the Twitter Terms of Service
get_twitter_configuration
(**params)¶Returns the current configuration used by Twitter
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.
get_user_suggestions
(**params)¶Access to Twitter’s suggested user list.
get_user_suggestions_by_slug
(**params)¶Access the users in a given category of the Twitter suggested user list.
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.
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
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: |
|
---|
(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.
is_list_subscriber
(**params)¶Check if the specified user is a subscriber of the specified list.
list_block_ids
(**params)¶Returns an array of numeric user ids the authenticating user is blocking.
list_blocks
(**params)¶Returns a collection of user objects that the authenticating user is blocking.
list_mute_ids
(**params)¶Returns an array of numeric user ids the authenticating user is muting.
list_mutes
(**params)¶Returns a collection of user objects that the authenticating user is muting.
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.
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.
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
Removes the uploaded profile banner for the authenticating user. Returns HTTP 200 upon success.
report_spam
(**params)¶Report the specified user as a spam account to Twitter.
request
(endpoint, method='GET', params=None, version='1.1', json_encoded=False)¶Return dict of response received from Twitter’s API
Parameters: |
|
---|---|
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.
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.
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.
show_lists
(**params)¶Returns all lists the authenticating or specified user subscribes to, including their own.
show_owned_lists
(**params)¶Returns the lists owned by the specified Twitter user.
show_saved_search
(**params)¶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.
subscribe_to_list
(**params)¶Subscribes the authenticated user to the specified list.
unsubscribe_from_list
(**params)¶Unsubscribes the authenticated user from the specified list.
update_account_settings
(**params)¶Updates the authenticating user’s 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.
update_list
(**params)¶Updates the specified list.
update_profile
(**params)¶Sets values that users are able to set under the “Account” tab of their settings page.
update_profile_background_image
(**params)¶Uploads a profile banner on behalf of the authenticating user.
Updates the authenticating user’s 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()
.
update_profile_image
(**params)¶Updates the authenticating user’s 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.
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.
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: |
|
---|
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: |
|
---|
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
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
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
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
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.
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.