tessl/pypi-tweepy
Library for accessing the X API (Twitter)
client-v2.mddocs/
Twitter API v2 Client
The Client class provides comprehensive access to Twitter API v2 endpoints with support for both app-only and user authentication contexts. It handles tweet management, user operations, timelines, search, lists, spaces, direct messages, and media uploads.
Capabilities
Client Initialization
Create a Client instance with authentication credentials and configuration options.
class Client:
def __init__(self, bearer_token=None, consumer_key=None, consumer_secret=None,
access_token=None, access_token_secret=None, *,
return_type=Response, wait_on_rate_limit=False):
"""
Initialize Twitter API v2 Client.
Parameters:
- bearer_token (str, optional): Bearer token for app-only authentication
- consumer_key (str, optional): Consumer key for user authentication
- consumer_secret (str, optional): Consumer secret for user authentication
- access_token (str, optional): Access token for user authentication
- access_token_secret (str, optional): Access token secret for user authentication
- return_type (type): Response container type (default: Response namedtuple)
- wait_on_rate_limit (bool): Wait when rate limit hit (default: False)
"""Tweet Management
Create, delete, and manage tweets with support for media attachments, polls, and reply settings.
def create_tweet(self, text=None, *, direct_message_deep_link=None,
for_super_followers_only=None, geo=None, media_ids=None,
place_id=None, poll_options=None, poll_duration_minutes=None,
quote_tweet_id=None, reply=None, reply_settings=None,
super_followers_only=None, user_auth=True):
"""
Create a new tweet.
Parameters:
- text (str, optional): Tweet text content (required unless media_ids provided)
- media_ids (list, optional): List of media IDs to attach
- poll_options (list, optional): Poll options (2-4 strings)
- poll_duration_minutes (int, optional): Poll duration (5-10080 minutes)
- reply (dict, optional): Reply configuration {"in_reply_to_tweet_id": "id"}
- quote_tweet_id (str, optional): ID of tweet to quote
- geo (dict, optional): Geographic information
- reply_settings (str, optional): "everyone", "mentionedUsers", "following"
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with created tweet data
"""
def delete_tweet(self, id, *, user_auth=True):
"""
Delete a tweet by ID.
Parameters:
- id (str): Tweet ID to delete
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with deletion confirmation
"""Tweet Interactions
Like, retweet, bookmark, and manage tweet interactions.
def like(self, tweet_id, *, user_auth=True):
"""
Like a tweet.
Parameters:
- tweet_id (str): ID of tweet to like
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with like status
"""
def unlike(self, tweet_id, *, user_auth=True):
"""
Remove like from a tweet.
Parameters:
- tweet_id (str): ID of tweet to unlike
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unlike status
"""
def retweet(self, tweet_id, *, user_auth=True):
"""
Retweet a tweet.
Parameters:
- tweet_id (str): ID of tweet to retweet
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with retweet status
"""
def unretweet(self, source_tweet_id, *, user_auth=True):
"""
Remove a retweet.
Parameters:
- source_tweet_id (str): ID of original tweet that was retweeted
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unretweet status
"""
def bookmark(self, tweet_id, *, user_auth=True):
"""
Add tweet to bookmarks.
Parameters:
- tweet_id (str): ID of tweet to bookmark
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with bookmark status
"""
def remove_bookmark(self, tweet_id, *, user_auth=True):
"""
Remove tweet from bookmarks.
Parameters:
- tweet_id (str): ID of tweet to remove from bookmarks
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with removal status
"""Tweet Lookup and Search
Retrieve tweets by ID, search recent and historical tweets, and get tweet quotes.
def get_tweet(self, id, *, expansions=None, media_fields=None, place_fields=None,
poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False):
"""
Get a single tweet by ID.
Parameters:
- id (str): Tweet ID
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include for authors
- media_fields (list, optional): Media fields to include
- poll_fields (list, optional): Poll fields to include
- place_fields (list, optional): Place fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with tweet data
"""
def get_tweets(self, ids, *, expansions=None, media_fields=None, place_fields=None,
poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False):
"""
Get multiple tweets by IDs.
Parameters:
- ids (list): List of tweet IDs (up to 100)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- media_fields (list, optional): Media fields to include
- poll_fields (list, optional): Poll fields to include
- place_fields (list, optional): Place fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with tweets data
"""
def search_recent_tweets(self, query, *, end_time=None, expansions=None,
max_results=None, media_fields=None, next_token=None,
place_fields=None, poll_fields=None, since_id=None,
sort_order=None, start_time=None, tweet_fields=None,
until_id=None, user_fields=None, user_auth=False):
"""
Search for tweets from the last 7 days.
Parameters:
- query (str): Search query string
- max_results (int, optional): Number of results to return (10-100, default: 10)
- next_token (str, optional): Pagination token
- since_id (str, optional): Return results after this tweet ID
- until_id (str, optional): Return results before this tweet ID
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
- end_time (str, optional): Latest tweet creation time (ISO 8601)
- sort_order (str, optional): "recency" or "relevancy"
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- media_fields (list, optional): Media fields to include
- poll_fields (list, optional): Poll fields to include
- place_fields (list, optional): Place fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with search results and metadata
"""
def search_all_tweets(self, query, *, end_time=None, expansions=None,
max_results=None, media_fields=None, next_token=None,
place_fields=None, poll_fields=None, since_id=None,
sort_order=None, start_time=None, tweet_fields=None,
until_id=None, user_fields=None, user_auth=False):
"""
Search the complete archive of public tweets (Academic Research access required).
Parameters: Same as search_recent_tweets
Returns:
Response with search results and metadata
"""
def get_quote_tweets(self, id, *, expansions=None, exclude=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=False):
"""
Get quotes of a specific tweet.
Parameters:
- id (str): Tweet ID to get quotes for
- max_results (int, optional): Number of results (10-100, default: 10)
- pagination_token (str, optional): Pagination token
- exclude (list, optional): Types to exclude ("retweets", "replies")
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with quote tweets
"""Tweet Analytics
Get engagement metrics and analytics for tweets and users.
def get_liked_tweets(self, id, *, expansions=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=True):
"""
Get tweets liked by a user.
Parameters:
- id (str): User ID
- max_results (int, optional): Number of results (5-100, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with liked tweets
"""
def get_liking_users(self, id, *, expansions=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=False):
"""
Get users who liked a specific tweet.
Parameters:
- id (str): Tweet ID
- max_results (int, optional): Number of results (1-100, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with users who liked the tweet
"""
def get_retweeters(self, id, *, expansions=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=False):
"""
Get users who retweeted a specific tweet.
Parameters:
- id (str): Tweet ID
- max_results (int, optional): Number of results (1-100, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with users who retweeted the tweet
"""
def get_recent_tweets_count(self, query, *, end_time=None, granularity=None,
since_id=None, start_time=None, until_id=None,
user_auth=False):
"""
Count tweets from the recent search index (last 7 days).
Parameters:
- query (str): Search query string
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
- end_time (str, optional): Latest tweet creation time (ISO 8601)
- since_id (str, optional): Count results after this tweet ID
- until_id (str, optional): Count results before this tweet ID
- granularity (str, optional): "minute", "hour", or "day"
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with tweet counts and time series data
"""
def get_all_tweets_count(self, query, *, end_time=None, granularity=None,
next_token=None, since_id=None, start_time=None,
until_id=None, user_auth=False):
"""
Count tweets from the full archive (Academic Research access required).
Parameters: Same as get_recent_tweets_count, plus:
- next_token (str, optional): Pagination token for large date ranges
Returns:
Response with tweet counts and time series data
"""Timelines
Access user timelines and tweet feeds.
def get_home_timeline(self, *, end_time=None, exclude=None, expansions=None,
max_results=None, pagination_token=None, since_id=None,
start_time=None, tweet_fields=None, until_id=None,
user_fields=None, user_auth=True):
"""
Get the authenticated user's home timeline.
Parameters:
- max_results (int, optional): Number of results (5-100, default: 100)
- pagination_token (str, optional): Pagination token
- exclude (list, optional): Types to exclude ("retweets", "replies")
- since_id (str, optional): Return results after this tweet ID
- until_id (str, optional): Return results before this tweet ID
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
- end_time (str, optional): Latest tweet creation time (ISO 8601)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with timeline tweets
"""
def get_users_tweets(self, id, *, end_time=None, exclude=None, expansions=None,
max_results=None, pagination_token=None, since_id=None,
start_time=None, tweet_fields=None, until_id=None,
user_fields=None, user_auth=False):
"""
Get tweets posted by a specific user.
Parameters:
- id (str): User ID
- max_results (int, optional): Number of results (5-100, default: 10)
- pagination_token (str, optional): Pagination token
- exclude (list, optional): Types to exclude ("retweets", "replies")
- since_id (str, optional): Return results after this tweet ID
- until_id (str, optional): Return results before this tweet ID
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
- end_time (str, optional): Latest tweet creation time (ISO 8601)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with user's tweets
"""
def get_users_mentions(self, id, *, end_time=None, expansions=None, max_results=None,
pagination_token=None, since_id=None, start_time=None,
tweet_fields=None, until_id=None, user_fields=None,
user_auth=True):
"""
Get tweets that mention a specific user.
Parameters:
- id (str): User ID
- max_results (int, optional): Number of results (5-100, default: 100)
- pagination_token (str, optional): Pagination token
- since_id (str, optional): Return results after this tweet ID
- until_id (str, optional): Return results before this tweet ID
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
- end_time (str, optional): Latest tweet creation time (ISO 8601)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with mention tweets
"""Reply Management
Hide and unhide replies to tweets.
def hide_reply(self, id, *, user_auth=True):
"""
Hide a reply to a tweet.
Parameters:
- id (str): Tweet ID of the reply to hide
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with hide status
"""
def unhide_reply(self, id, *, user_auth=True):
"""
Unhide a previously hidden reply.
Parameters:
- id (str): Tweet ID of the reply to unhide
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unhide status
"""User Management
Get user information and manage the authenticated user's profile.
def get_me(self, *, expansions=None, tweet_fields=None, user_fields=None,
user_auth=True):
"""
Get the authenticated user's information.
Parameters:
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweet
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with authenticated user's data
"""
def get_user(self, *, id=None, username=None, expansions=None, tweet_fields=None,
user_fields=None, user_auth=False):
"""
Get a user by ID or username.
Parameters:
- id (str, optional): User ID (required if username not provided)
- username (str, optional): Username handle (required if id not provided)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweet
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with user data
"""
def get_users(self, *, ids=None, usernames=None, expansions=None, tweet_fields=None,
user_fields=None, user_auth=False):
"""
Get multiple users by IDs or usernames.
Parameters:
- ids (list, optional): List of user IDs (up to 100)
- usernames (list, optional): List of usernames (up to 100)
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweets
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with users data
"""User Relationships
Follow, unfollow, block, mute, and manage user relationships.
def follow_user(self, target_user_id, *, user_auth=True):
"""
Follow a user.
Parameters:
- target_user_id (str): ID of user to follow
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with follow status
"""
def unfollow_user(self, target_user_id, *, user_auth=True):
"""
Unfollow a user.
Parameters:
- target_user_id (str): ID of user to unfollow
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unfollow status
"""
def follow(self, target_user_id, *, user_auth=True):
"""
Follow a user (alias for follow_user).
Parameters:
- target_user_id (str): ID of user to follow
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with follow status
"""
def unfollow(self, target_user_id, *, user_auth=True):
"""
Unfollow a user (alias for unfollow_user).
Parameters:
- target_user_id (str): ID of user to unfollow
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unfollow status
"""
def get_users_followers(self, id, *, expansions=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=False):
"""
Get a user's followers.
Parameters:
- id (str): User ID
- max_results (int, optional): Number of results (1-1000, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweets
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with followers data
"""
def get_users_following(self, id, *, expansions=None, max_results=None,
pagination_token=None, tweet_fields=None, user_fields=None,
user_auth=False):
"""
Get users that a user is following.
Parameters:
- id (str): User ID
- max_results (int, optional): Number of results (1-1000, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweets
- user_fields (list, optional): User fields to include
- user_auth (bool): Use user authentication (default: False)
Returns:
Response with following data
"""
def block(self, target_user_id, *, user_auth=True):
"""
Block a user.
Parameters:
- target_user_id (str): ID of user to block
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with block status
"""
def unblock(self, target_user_id, *, user_auth=True):
"""
Unblock a user.
Parameters:
- target_user_id (str): ID of user to unblock
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unblock status
"""
def get_blocked(self, *, expansions=None, max_results=None, pagination_token=None,
tweet_fields=None, user_fields=None, user_auth=True):
"""
Get the authenticated user's blocked users.
Parameters:
- max_results (int, optional): Number of results (1-1000, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweets
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with blocked users data
"""
def mute(self, target_user_id, *, user_auth=True):
"""
Mute a user.
Parameters:
- target_user_id (str): ID of user to mute
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with mute status
"""
def unmute(self, target_user_id, *, user_auth=True):
"""
Unmute a user.
Parameters:
- target_user_id (str): ID of user to unmute
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with unmute status
"""
def get_muted(self, *, expansions=None, max_results=None, pagination_token=None,
tweet_fields=None, user_fields=None, user_auth=True):
"""
Get the authenticated user's muted users.
Parameters:
- max_results (int, optional): Number of results (1-1000, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields for pinned tweets
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with muted users data
"""Bookmarks
Manage the authenticated user's bookmarks.
def get_bookmarks(self, *, expansions=None, max_results=None, pagination_token=None,
tweet_fields=None, user_fields=None, user_auth=True):
"""
Get the authenticated user's bookmarks.
Parameters:
- max_results (int, optional): Number of results (1-100, default: 100)
- pagination_token (str, optional): Pagination token
- expansions (list, optional): Additional data to include
- tweet_fields (list, optional): Tweet fields to include
- user_fields (list, optional): User fields to include
- user_auth (bool): Requires user authentication (default: True)
Returns:
Response with bookmarked tweets
"""Note: This document continues with additional Client methods for Lists, Spaces, Direct Messages, Compliance, and Media Upload. The complete Client class contains over 80 methods covering all Twitter API v2 endpoints.
Install with Tessl CLI
npx tessl i tessl/pypi-tweepy