Skip to content

4. API Reference

Jump to bottom
Dev Jones edited this page Mar 25, 2024 · 13 revisions

This section of the documentation serves as a comprehensive guide to the classes, methods, and models available in PyTweetToolkit. Here, you can find detailed information on how to use the toolkit to interact with Twitter.

Overview

  • Brief description of the API
  • Authentication requirements
  • Rate limiting and best practices

Bookmark Actions

The BookmarkActions class in PyTweetToolkit is dedicated to managing Twitter bookmarks. This class allows users to bookmark tweets, remove bookmarks, and retrieve a list of bookmarked tweets using Twitter's GraphQL API. It inherits from an authentication base class for necessary credentials handling.

Rate Limits:

  • bookmark_tweet: 500 actions per 15-minute window
  • unbookmark_tweet: 500 actions per 15-minute window
  • get_bookmarks: 500 actions per 15-minute window

Methods:

Bookmark Tweet

  • bookmark_tweet(tweet_id: str) -> tweet_model.Tweet

    Bookmarks a specified tweet.

    • Parameters: tweet_id (str) - The ID of the tweet to bookmark.
    • Returns: tweet_model.Tweet - An instance representing the bookmarked tweet.
    • Raises: HTTP errors or specific exceptions based on API response.
    • Rate Limit: 500 actions per 15 minutes.

Unbookmark Tweet

  • unbookmark_tweet(tweet_id: str) -> tweet_model.Tweet

    Removes a bookmark from a specified tweet.

    • Parameters: tweet_id (str) - The ID of the tweet to unbookmark.
    • Returns: tweet_model.Tweet - An instance representing the tweet post-unbookmark.
    • Raises: HTTP errors or specific exceptions based on API response.
    • Rate Limit: 500 actions per 15 minutes.

Get bookmarks

  • get_bookmarks(cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Fetches a list of bookmarked tweets, with pagination support.

    • Parameters: cursor (str, optional) - Pagination cursor for bookmark retrieval.
    • Returns: tuple[list[tweet_model.Tweet], str, str] - A tuple containing a list of bookmarked tweets, the next cursor, and the previous cursor.
    • Raises: HTTP errors or specific exceptions based on API response.
    • Rate Limit: 500 actions per 15 minutes.

Friendship Actions

The FriendshipActions class in PyTweetToolkit handles various actions related to Twitter friendships. This includes following and unfollowing users, as well as managing follow requests, all through Twitter's API. It uses authentication from the base class for API requests.

Rate Limits:

  • The update actions are subject to Twitter's standard API rate limits.

Methods:

Follow User

  • follow_user(user_id: str) -> user_model.User

    Initiates following a user by their ID and returns details about the followed user.

    • Parameters: user_id (str) - The ID of the user to follow.
    • Returns: user_model.User - Details of the followed user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Unfollow User

  • unfollow_user(user_id: str) -> user_model.User

    Stops following a user by their ID and returns details about the unfollowed user.

    • Parameters: user_id (str) - The ID of the user to unfollow.
    • Returns: user_model.User - Details of the unfollowed user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Follow Requests

  • follow_requests(user_id: str) -> list[user_model.User]

    Retrieves a list of users who have requested to follow the authenticated user.

    • Parameters: user_id (str) - The user ID of the authenticated user.
    • Returns: list[user_model.User] - A list of users who have requested to follow.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Accept Follow Request

  • accept_follow_request(user_id: str) -> user_model.User

    Accepts a follow request from a specific user by their ID, returning the user's details post-acceptance.

    • Parameters: user_id (str) - The ID of the user whose follow request is accepted.
    • Returns: user_model.User - The user's details after accepting the follow request.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Reject Follow Request

  • reject_follow_request(user_id: str) -> user_model.User

    Rejects a follow request from a specific user by their ID, returning the user's details post-rejection.

    • Parameters: user_id (str) - The ID of the user whose follow request is rejected.
    • Returns: user_model.User - The user's details after rejecting the follow request.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Interaction Actions

The InteractionActions class within PyTweetToolkit facilitates various interactions with tweets, such as liking, unliking, retweeting, deleting retweets, and creating replies. These functions leverage Twitter's API, with authentication inherited from a base class.

Rate Limits:

  • like_tweet: 500 actions per 15-minute window.
  • unlike_tweet: 500 actions per 15-minute window.
  • create_retweet: Subject to Twitter's standard API rate limits.
  • delete_retweet: Subject to Twitter's standard API rate limits.
  • create_reply: Subject to Twitter's standard API rate limits.

Methods:

Like Tweet

  • like_tweet(tweet_id: str) -> str

    Likes a tweet based on the provided tweet ID.

    • Parameters: tweet_id (str) - The ID of the tweet to like.
    • Returns: str - 'Success' if liked successfully, 'Failed' otherwise.
    • Rate Limit: 500 actions per 15 minutes.

Unlike Tweet

  • unlike_tweet(tweet_id: str) -> str

    Removes a like from a tweet based on the provided tweet ID.

    • Parameters: tweet_id (str) - The ID of the tweet to unlike.
    • Returns: str - 'Success' if unliked successfully, 'Failed' otherwise.
    • Rate Limit: 500 actions per 15 minutes.

Create Retweet

  • create_retweet(source_tweet_id: str) -> tweet_model.Tweet

    Retweets a tweet given the source tweet's ID.

    • Parameters: source_tweet_id (str) - The ID of the tweet to retweet.
    • Returns: tweet_model.Tweet - Details of the retweet.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Delete Retweet

  • delete_retweet(source_tweet_id: str) -> tweet_model.Tweet

    Deletes a retweet of the given source tweet ID.

    • Parameters: source_tweet_id (str) - The ID of the source tweet whose retweet is to be deleted.
    • Returns: tweet_model.Tweet - Details of the original tweet.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Create Reply

  • create_reply(reply_to_tweet_id: str, content: str = "", media_ids: list = []) -> tweet_model.Tweet

    Creates a reply to a specified tweet, with optional content and media attachments.

    • Parameters:
      • reply_to_tweet_id (str) - The ID of the tweet to reply to.
      • content (str, optional) - The content of the reply.
      • media_ids (list, optional) - List of media IDs to attach.
    • Returns: tweet_model.Tweet - Details of the reply tweet.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Notification Actions

The NotificationActions class in PyTweetToolkit is designed for managing user notifications on Twitter, encompassing functionalities to fetch all notifications, notifications from verified accounts, and mention notifications, all through the platform's API.

Rate Limits:

  • All notification retrieval methods are limited to 180 actions per 15-minute window.

Methods:

Get All Notifications

  • get_all_notifications(cursor: str = "") -> tuple[list[notification_model.Notification], str, str]

    Retrieves all notifications for the authenticated user, including likes, retweets, follows, and mentions, providing a comprehensive overview of user engagement.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching a specific page of notifications.
    • Returns: A tuple containing a list of notification_model.Notification objects, the next cursor, and the previous cursor for pagination.
    • Rate Limit: 180 actions per 15 minutes.

Get Verified Notifications

  • get_verified_notifications(cursor: str = "") -> tuple[list[notification_model.Notification], str, str]

    Specifically fetches notifications originating from verified accounts, offering insights into interactions with public figures or official accounts.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching a specific page of verified account notifications.
    • Returns: A tuple containing a list of notification_model.Notification objects from verified accounts, the next cursor, and the previous cursor.
    • Rate Limit: 180 actions per 15 minutes.

Get Mention Notifications

  • get_mention_notifications(cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Focuses on fetching notifications for mentions, showing tweets where the user is mentioned by others, which is crucial for engagement and interaction tracking.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching a specific page of mention notifications.
    • Returns: A tuple containing a list of tweet_model.Tweet objects mentioning the user, the next cursor, and the previous cursor for pagination.
    • Rate Limit: 180 actions per 15 minutes.

Profile Actions

The ProfileActions class in PyTweetToolkit provides functionalities for managing user profile actions on Twitter. This includes updating profile details such as the user's name, description, location, website URL, profile image, and banner, utilizing the platform's API.

Rate Limits:

  • The update actions are subject to Twitter's standard API rate limits.

Methods:

Update Profile

  • update_profile(name: str = None, description: str = None, location: str = None, website_url: str = None) -> user_model.User

    Updates the authenticated user's profile details, with options to modify the name, description, location, and website URL.

    • Parameters: Optional parameters for name, description, location, and website_url.
    • Returns: The updated user_model.User reflecting the changes.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Update Profile Image

  • update_profile_image(source: str) -> user_model.User

    Updates the user's profile image using a specified image file. The method requires the local path to the image file.

    • Parameters: source (str) - The file path to the new profile image.
    • Returns: The updated user_model.User with the new profile image.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Update Profile Banner

  • update_profile_banner(source: str) -> user_model.User

    Updates the user's profile banner to a new image provided via a file path. This method allows personalizing the profile banner.

    • Parameters: source (str) - The file path to the new profile banner image.
    • Returns: The updated user_model.User with the new profile banner.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Restriction Actions

The RestrictionActions class in PyTweetToolkit is tailored for managing user restrictions on Twitter, including blocking and muting users, via the platform's API. This functionality is crucial for moderating interactions and maintaining a user's privacy and comfort on the social network.

Rate Limits:

  • All methods related to user restrictions adhere to Twitter's standard API rate limits.

Methods:

Block User

  • block_user(user_id: str) -> user_model.User

    Initiates blocking a specific user by their user ID, preventing them from interacting with the authenticated user's tweets.

    • Parameters: user_id (str) - The ID of the user to block.
    • Returns: The user_model.User containing details of the blocked user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Unblock User

  • unblock_user(user_id: str) -> user_model.User

    Reverses a block action, allowing the previously blocked user to interact with the authenticated user's tweets once more.

    • Parameters: user_id (str) - The ID of the user to unblock.
    • Returns: The user_model.User containing details of the unblocked user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Mute User

  • mute_user(user_id: str) -> user_model.User

    Mutes a specific user by their user ID, hiding their tweets from the authenticated user's timeline without blocking them.

    • Parameters: user_id (str) - The ID of the user to mute.
    • Returns: The user_model.User containing details of the muted user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Unmute User

  • unmute_user(user_id: str) -> user_model.User

    Removes a mute, allowing the authenticated user to see the previously muted user's tweets in their timeline again.

    • Parameters: user_id (str) - The ID of the user to unmute.
    • Returns: The user_model.User containing details of the unmuted user.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Get Blocked Users

  • get_blocked_users(cursor: str = "") -> tuple[list[user_model.User], str, str]

    Retrieves a list of users who have been blocked by the authenticated user, including pagination cursors for extended lists.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching a specific set of blocked users.
    • Returns: A tuple containing a list of user_model.User objects (blocked users), the next cursor, and the previous cursor.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Get Muted Users

  • get_muted_users(cursor: str = "") -> tuple[list[user_model.User], str, str]

    Fetches a list of users muted by the authenticated user, alongside pagination cursors for navigating through the list.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching a specific set of muted users.
    • Returns: A tuple containing a list of user_model.User objects (muted users), the next cursor, and the previous cursor.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Search Actions

The SearchActions class in PyTweetToolkit encompasses a suite of functionalities for performing various search operations within Twitter. This includes finding top content, latest tweets, user profiles, media, and lists based on specific queries, all facilitated through Twitter's API.

Rate Limits:

  • All search methods are capped at 50 requests per 15-minute window, aligning with Twitter's standard API rate limitations.

Methods:

Top Content Search

  • search_top(query: str, cursor: str = "") -> tuple[list[user_model.User], list[tweet_model.Tweet], str, str]

    Conducts a search for top content related to a specified query, returning both users and tweets among the top results.

    • Parameters:
      • query (str) - The search query.
      • cursor (str, optional) - Pagination cursor for fetching a specific set of results.
    • Returns: A tuple containing lists of user_model.User and tweet_model.Tweet, along with next and previous cursors for pagination.

Latest Tweets Search

  • search_latest(query: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Searches for the latest tweets matching the provided query.

    • Parameters: Identical to the top content search.
    • Returns: A tuple containing a list of tweet_model.Tweet, next cursor, and previous cursor.

People Search

  • search_people(query: str, cursor: str = "") -> tuple[list[user_model.User], str, str]

    Finds user profiles relevant to the search query.

    • Parameters: Identical to the top content search.
    • Returns: A tuple containing a list of user_model.User, next cursor, and previous cursor.

Media Search

  • search_media(query: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Retrieves media tweets that are related to the specified query.

    • Parameters: Identical to the top content search.
    • Returns: A tuple containing a list of tweet_model.Tweet (with media), next cursor, and previous cursor.

Lists Search

  • search_lists(query: str, cursor: str = "") -> tuple[list[list_model.List], str, str]

    Searches for Twitter lists that match the search query.

    • Parameters: Identical to the top content search.
    • Returns: A tuple containing a list of list_model.List, next cursor, and previous cursor.

Tweet Actions

The TweetActions class in PyTweetToolkit is centered around managing tweet-related activities on Twitter. This includes obtaining tweets from specific users, individual tweets, conversation threads, tweets within a list, and user timelines. It effectively utilizes authenticated API requests for diverse tweet operations.

Rate Limits:

  • get_user_tweets: 50 requests per 15-minute window.
  • get_tweet: 150 requests per 15-minute window.
  • get_tweet_conversation: 150 requests per 15-minute window.
  • get_tweets_from_list: 500 requests per 15-minute window.
  • create_tweet & delete_tweet: Subject to Twitter's standard API rate limits.

Methods:

Get User Tweets

  • get_user_tweets(user_id: str, cursor: str = "", is_reply=False, is_retweet=False) -> tuple[list[tweet_model.Tweet], str, str]

    Retrieves tweets made by a specific user. This method offers options to filter solely for replies or retweets.

    • Parameters: user_id (str), cursor (str, optional), flags for is_reply and is_retweet.
    • Returns: A tuple consisting of a list of tweet_model.Tweet, next cursor, and previous cursor.

Get Tweet

  • get_tweet(tweet_id: str) -> tweet_model.Tweet

    Fetches an individual tweet based on its ID.

    • Parameters: tweet_id (str).
    • Returns: The tweet_model.Tweet associated with the given ID.

Get Tweet Conversation

  • get_tweet_conversation(tweet_id: str) -> list[tweet_model.Tweet]

    Obtains the conversation thread for a specified tweet.

    • Parameters: tweet_id (str).
    • Returns: A list of tweet_model.Tweet forming the conversation thread.

Get Tweets from List

  • get_tweets_from_list(list_id: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Gathers tweets posted by members of a specified list.

    • Parameters: list_id (str), cursor (str, optional).
    • Returns: A tuple containing a list of tweet_model.Tweet, next cursor, and previous cursor.

Get 'For You' Timeline

  • get_for_you_timeline(cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Retrieves tweets from the 'For You' timeline, personalized based on the user's interactions and preferences.

    • Parameters: cursor (str, optional) - Pagination cursor for fetching tweets.
    • Returns: A tuple comprising a list of tweet_model.Tweet, the next cursor, and the previous cursor.
    • Rate Limit: 500 requests per 15-minute window.

Get Following Timeline

  • get_following_timeline(cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Fetches tweets from the timeline of accounts the user follows, presenting a broad view of current discussions and updates.

    • Parameters: Identical to the 'For You' timeline method.
    • Returns: Similar tuple structure containing tweet models and pagination cursors.
    • Rate Limit: 500 requests per 15-minute window.

Create Tweet

  • create_tweet(content: str = "", media_ids: list = [], reply_to_tweet_id: str = None, quote_tweet_id: str = None) -> tweet_model.Tweet

    Allows the creation of a new tweet, with options for text content, media attachment, replying to an existing tweet, or quoting another tweet.

    • Parameters: content (str, optional), media_ids (list, optional), reply_to_tweet_id (str, optional), quote_tweet_id (str, optional).
    • Returns: The tweet_model.Tweet representing the newly created tweet.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Delete Tweet

  • delete_tweet(tweet_id: str) -> None

    Permits the deletion of a specific tweet by its ID, removing it from the platform.

    • Parameters: tweet_id (str) - The ID of the tweet to be deleted.
    • Returns: None, indicating successful deletion.
    • Rate Limit: Subject to Twitter's standard API rate limits.

Upload Actions

The UploadActions class in PyTweetToolkit facilitates the uploading of media files to Twitter, accommodating a variety of media types including images and videos. This class orchestrates the entire upload process, from initialization and media upload to finalization, all while ensuring compliance with Twitter's media requirements.

Rate Limits:

  • The upload process is governed by Twitter's media upload endpoints, typically allowing 615 media uploads per 15-minute window.

Methods:

Upload Media

  • upload(source: str, media_category: str = None) -> str

    Manages the upload of a media file to Twitter, supporting both images and videos. The method checks the file for compliance with Twitter's media specifications before initiating the upload. Depending on the nature of the media (e.g., image, video, GIF), it categorizes the media for appropriate handling on the platform.

    • Parameters:
      • source (str) - The local file path or URL of the gif to be uploaded.
      • media_category (str, optional) - Specifies the media category, such as "tweet_image", "tweet_video", "tweet_gif", "dm_image", "dm_video", or "dm_gif". If unspecified, default handling is applied.
    • Returns: The media ID string, usable in tweets or direct messages.
    • Rate Limit: 615 requests per 15-minute window.
    • Raises: FileNotFoundError if the file path doesn't exist, ValueError for invalid media categories or non-compliant files.

User Actions

The UserActions class in PyTweetToolkit is designed for managing various actions related to Twitter users. It enables the retrieval of user profiles, followers, followings, media content, likes, and retweets. This functionality is vital for applications that require detailed information about users and their interactions on Twitter.

Rate Limits:

  • get_user_by_screen_name: 95 requests per 15-minute window.
  • get_user_following: 500 requests per 15-minute window.
  • get_user_followers: 50 requests per 15-minute window.
  • get_user_media: 500 requests per 15-minute window.
  • get_user_likes: 500 requests per 15-minute window.
  • get_user_retweets: Subject to Twitter's standard API rate limits.

Methods:

Get User by Screen Name

  • get_user_by_screen_name(screen_name: str) -> user_model.User

    Retrieves a user's profile using their Twitter handle.

    • Rate Limit: 95 requests per 15-minute window.
    • Parameters: screen_name (str) - The Twitter handle of the user.
    • Returns: user_model.User containing the profile details of the specified user.

Get User Following

  • get_user_following(user_id: str, cursor: str = "") -> tuple[list[user_model.User], str, str]

    Fetches the list of users that a specified user follows.

    • Rate Limit: 500 requests per 15-minute window.
    • Parameters: user_id (str), cursor (str, optional) for pagination.
    • Returns: A tuple containing a list of user_model.User (users being followed), next cursor, and previous cursor.

Get User Followers

  • get_user_followers(user_id: str, cursor: str = "") -> tuple[list[user_model.User], str, str]

    Obtains the followers of a specified user.

    • Rate Limit: 50 requests per 15-minute window.
    • Parameters: Similar to get_user_following.
    • Returns: A tuple containing a list of user_model.User (followers), next cursor, and previous cursor.

Get User Media

  • get_user_media(user_id: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Retrieves media content (images, videos) posted by a user.

    • Rate Limit: 500 requests per 15-minute window.
    • Parameters: user_id (str), cursor (str, optional).
    • Returns: A tuple containing a list of tweet_model.Tweet (media tweets), next cursor, and previous cursor.

Get User Likes

  • get_user_likes(user_id: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Fetches tweets liked by a user, reflecting their interests.

    • Rate Limit: 500 requests per 15-minute window.
    • Parameters: Identical to get_user_media.
    • Returns: A tuple containing a list of tweet_model.Tweet (liked tweets), next cursor, and previous cursor.

Get User Retweets

  • get_user_retweets(user_id: str, cursor: str = "") -> tuple[list[tweet_model.Tweet], str, str]

    Collects tweets retweeted by the user, showcasing their shared content.

    • Rate Limit: Subject to Twitter's standard API rate limits.
    • Parameters: user_id (str), cursor (str, optional).
    • Returns: A tuple containing a list of tweet_model.Tweet (retweeted tweets), next cursor, and previous cursor.
Clone this wiki locally