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(self, 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(self, 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(self, 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: These actions adhere to Twitter's standard API rate limits.

Methods:

Follow User

  • follow_user(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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.

Clone this wiki locally