Actively maintained, pure Python wrapper for the Twitter API. Supports both normal and streaming Twitter APIs
Information on how to properly install Twython
Install Twython via pip
$ pip install twython
or, with easy_install
$ easy_install twython
But, hey… that’s up to you.
Twython is actively maintained on GitHub
Feel free to clone the repository
git clone git://github.com/ryanmcgrath/twython.git
$ curl -OL https://github.com/ryanmcgrath/twython/tarball/master
$ curl -OL https://github.com/ryanmcgrath/twython/zipball/master
Now that you have the source code, install it into your site-packages directory
$ python setup.py install
So Twython is installed! Now, head over to the starting out section.
This section is going to help you understand creating a Twitter Application, authenticating a user, and making basic API calls
First, you’ll want to head over to https://apps.twitter.com/ and register an application!
After you register, grab your applications Consumer Key and Consumer Secret from the application details tab.
Now you’re ready to start authentication!
Twython offers support for both OAuth 1 and OAuth 2 authentication.
The difference:
Important
Again, if your web app is planning on using interacting with users, this IS the authentication type for you. If you’re not interested in authenticating a user and plan on making read-only calls, check out the OAuth 2 section.
First, you’ll want to import Twython
from twython import Twython
Now, you’ll want to create a Twython instance with your Consumer Key and Consumer Secret
Note
Only pass callback_url to get_authentication_tokens if your application is a Web Application
Desktop and Mobile Applications do not require a callback_url
APP_KEY = 'YOUR_APP_KEY'
APP_SECRET = 'YOUR_APP_SECRET'
twitter = Twython(APP_KEY, APP_SECRET)
auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback')
From the auth variable, save the oauth_token_secret for later use (these are not the final auth tokens). In Django or other web frameworks, you might want to store it to a session variable
OAUTH_TOKEN = auth['oauth_token']
OAUTH_TOKEN_SECRET = auth['oauth_token_secret']
Send the user to the authentication url, you can obtain it by accessing
auth['auth_url']
Note
If your application is a Desktop or Mobile Application oauth_verifier will be the PIN code
After they authorize your application to access some of their account details, they’ll be redirected to the callback url you specified in get_autentication_tokens
You’ll want to extract the oauth_verifier from the url.
Django example:
oauth_verifier = request.GET['oauth_verifier']
Now that you have the oauth_verifier stored to a variable, you’ll want to create a new instance of Twython and grab the final user tokens
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
final_step = twitter.get_authorized_tokens(oauth_verifier)
Once you have the final user tokens, store them in a database for later use!
OAUTH_TOKEN = final_step['oauth_token']
OAUTH_TOKEN_SECRET = final_step['oauth_token_secret']
Attention
Just a reminder, this authentication type is for when you don’t want to authenticate and interact with users and make read-only calls to Twitter
OAuth 2 authentication is 100x easier than OAuth 1.
Let’s say you just made your application and have your Consumer Key and Consumer Secret
First, you’ll want to import Twython
from twython import Twython
APP_KEY = 'YOUR_APP_KEY'
APP_SECRET = 'YOUR_APP_SECRET'
twitter = Twython(APP_KEY, APP_SECRET, oauth_version=2)
ACCESS_TOKEN = twitter.obtain_access_token()
Save ACCESS_TOKEN in a database or something for later use!
The Twython package contains a file endpoints.py which holds a Mixin of all Twitter API endpoints. This is so Twython’s core api.py isn’t cluttered with 50+ methods.
Keyword arguments to functions are mapped to the functions available for each endpoint in the Twitter API docs. Doing this allows us to be incredibly flexible in querying the Twitter API, so changes to the API aren’t held up from you using them by this library.
Twython returns native Python objects. We convert the JSON sent to us from Twitter to an object so you don’t have to.
Now that you have a little idea of the type of data you’ll be receiving, briefed on how arguments are handled, and your application tokens and user oauth tokens (or access token if you’re using OAuth 2), check out the basic usage section.
This section will cover how to use Twython and interact with some basic Twitter API calls
Before you make any API calls, make sure you authenticated the user (or app)!
Note
All sections on this page will assume you’re using a Twython instance
Create a Twython instance with your application keys and the users OAuth tokens
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
Documentation: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials
twitter.verify_credentials()
Documentation: https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline
twitter.get_home_timeline()
This method makes use of dynamic arguments, read more about them
Documentation: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update
twitter.update_status(status='See how easy using Twython is!')
Create a Twython instance with your application key and access token
from twython import Twython
twitter = Twython(APP_KEY, access_token=ACCESS_TOKEN)
Note
Searching can be done whether you’re authenticated via OAuth 1 or OAuth 2
Documentation: https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets
twitter.search(q='python')
Important
To help explain dynamic function arguments a little more, you can see that the previous call used the keyword argument q, that is because Twitter specifies in their search documentation that the search call accepts the parameter “q”. You can pass mutiple keyword arguments. The search documentation also specifies that the call accepts the parameter “result_type”
twitter.search(q='python', result_type='popular')
So, now, you’re pretty well versed on making authenticated calls to Twitter using Twython. Check out the advanced usage section, for some functions that may be a little more complicated.
This section will cover how to use Twython and interact with some more advanced API calls
Before you make any API calls, make sure you authenticated the user (or app)!
Note
All sections on this page will assume you’re using a Twython instance
Create a Twython instance with your application keys and the users OAuth tokens
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
This uploads an image as a media object and associates it with a status update.
photo = open('/path/to/file/image.jpg', 'rb')
response = twitter.upload_media(media=photo)
twitter.update_status(status='Checkout this cool image!', media_ids=[response['media_id']])
Documentation:
This uploads a video as a media object and associates it with a status update.
video = open('/path/to/file/video.mp4', 'rb')
response = twitter.upload_video(media=video, media_type='video/mp4')
twitter.update_status(status='Checkout this cool video!', media_ids=[response['media_id']])
Documentation:
This example resizes an image, then uploads it as a media object and associates it with a status update.
# Assume you are working with a JPEG
from PIL import Image
try:
# Python 3
from io import StringIO
except ImportError:
# Python 2
from StringIO import StringIO
photo = Image.open('/path/to/file/image.jpg')
basewidth = 320
wpercent = (basewidth / float(photo.size[0]))
height = int((float(photo.size[1]) * float(wpercent)))
photo = photo.resize((basewidth, height), Image.ANTIALIAS)
image_io = StringIO.StringIO()
photo.save(image_io, format='JPEG')
# If you do not seek(0), the image will be at the end of the file and
# unable to be read
image_io.seek(0)
response = twitter.upload_media(media=image_io)
twitter.update_status(status='Checkout this cool image!', media_ids=[response['media_id']])
So, if you’re pretty into Python, you probably know about generators
That being said, Twython offers a generator for search results and can be accessed by using the following code:
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)
There are times when you may want to turn SSL verification off, send custom headers, or add proxies for the request to go through.
Twython uses the requests library to make API calls to Twitter. requests accepts a few parameters to allow developers to manipulate the acutal HTTP request.
Here is an example of sending custom headers to a Twitter API request:
from twython import Twython
client_args = {
'headers': {
'User-Agent': 'My App Name'
}
}
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET,
client_args=client_args)
Here is an example of sending the request through proxies:
from twython import Twython
client_args = {
'proxies': {
'http': 'http://10.0.10.1:8000',
'https': 'https://10.0.10.1:8001',
}
}
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET,
client_args=client_args)
or both (and set a timeout variable):
from twython import Twython
client_args = {
'headers': {
'User-Agent': 'My App Name'
},
'proxies': {
'http': 'http://10.0.10.1:8000',
'https': 'https://10.0.10.1:8001',
}
'timeout': 300,
}
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET,
client_args=client_args)
There are times when you may want to check headers from the previous call.
If you wish to access headers (ex. x-rate-limit-remaining, x-rate-limit-reset, content-type), you’ll use the get_lastfunction_header method.
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
twitter.get_home_timeline()
twitter.get_lastfunction_header('x-rate-limit-remaining')
So now you can authenticate, update your status (with or without an image), search Twitter, and a few other things! Good luck!
This section will cover how to use Twython and interact with the Twitter Streaming API.
Streaming Documentation: https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/streaming-message-types
Important
The Streaming API requires that you have OAuth 1 authentication credentials. If you don’t have credentials, head over to the authentication section and find out how!
Note
When stream data is sent back to Twython, we send the data through signals (i.e. on_success, on_error, etc.)
Make sure you import TwythonStreamer
from twython import TwythonStreamer
Now set up how you want to handle the signals.
class MyStreamer(TwythonStreamer):
def on_success(self, data):
if 'text' in data:
print(data['text'])
def on_error(self, status_code, data):
print(status_code)
# Want to stop trying to get data because of the error?
# Uncomment the next line!
# self.disconnect()
More signals that you can extend on can be found in the Developer Interface section under Streaming Interface
stream = MyStreamer(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
stream.statuses.filter(track='twitter')
With the code above, data should be flowing in.
This section covers methods to are part of Twython but not necessarily connected to the Twitter API.
This function returns a generator for Twitter API endpoints that are able to be pagintated in some way (either by cursor or since_id parameter)
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
results = twitter.search(q='twitter')
if results.get('statuses'):
for result in results['statuses']:
print(result['id_str'])
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
results = twitter.cursor(twitter.search, q='twitter')
for result in results:
print(result['id_str'])
Another example:
results = twitter.cursor(twitter.get_mentions_timeline)
for result in results:
print(result['id_str'])
By default, the cursor yields one item at a time. If instead you prefer to work with entire pages of results, specify return_pages=True as a keyword argument.
results = twitter.cursor(twitter.get_mentions_timeline, return_pages=True)
# page is a list
for page in results:
for result in page:
print(result['id_str'])
This function takes a tweet object received from the Twitter API and returns an string formatted in HTML with the links, user mentions and hashtags replaced.
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
user_tweets = twitter.get_user_timeline(screen_name='mikehelmick',
include_rts=True)
for tweet in user_tweets:
tweet['text'] = Twython.html_for_tweet(tweet)
print(tweet['text'])
The above code takes all the tweets from a specific users timeline, loops over them and replaces the value of tweet['text'] with HTML.
So:
http://t.co/FCmXyI6VHd is #cool, lol! @mikehelmick shd #checkitout. Love, @__twython__ $IBM https://t.co/67pwRvY6z9 http://t.co/N6InAO4B71
will be replaced with:
<a href=”http://t.co/FCmXyI6VHd” class=”twython-url”>google.com</a> is <a href=”https://twitter.com/search?q=%23cool” class=”twython-hashtag”>#cool</a>, lol! <a href=”https://twitter.com/mikehelmick” class=”twython-mention”>@mikehelmick</a> shd <a href=”https://twitter.com/search?q=%23checkitout” class=”twython-hashtag”>#checkitout</a>. Love, <a href=”https://twitter.com/__twython__” class=”twython-mention”>@__twython__</a> <a href=”https://twitter.com/?q=%24IBM” class=”twython-symbol”>$IBM</a> <a href=”https://t.co/67pwRvY6z9” class=”twython-url”>github.com</a> <a href=”http://t.co/N6InAO4B71” class=”twython-media”>pic.twitter.com/N6InAO4B71</a>
Note
When converting the string to HTML we add a class to each HTML tag so that you can maninpulate the DOM later on.
class="twython-url" to the anchor tagclass="twython-media" to the anchor tagclass="twython-mention" to the anchor tagclass="twython-hashtag" to the anchor tagclass="twython-symbol" to the anchor tagThis function accepts two parameters: use_display_url and use_expanded_url
By default, use_display_url is True. Meaning the link displayed in the tweet text will appear as (ex. google.com, github.com)
If use_expanded_url is True, it overrides use_display_url. The urls will then be displayed as (ex. http://google.com, https://github.com)
If use_display_url and use_expanded_url are False, short url will be used (t.co/xxxxx)
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, to| Parameters: |
|
|---|---|
| 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.