tweetapi 1.1.0__py3-none-any.whl

tweetapi/__init__.py

@@ -0,0 +1,40 @@
+"""TweetAPI Python SDK — Official client for the Twitter/X Data API.
+
+Usage::
+
+    from tweetapi import TweetAPI
+
+    client = TweetAPI(api_key="YOUR_API_KEY")
+
+    user = client.user.get_by_username(username="elonmusk")
+    print(user["data"]["followerCount"])
+"""
+
+from .client import TweetAPI
+from .errors import (
+    TweetAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    ConnectionError_ as NetworkError,
+)
+from .pagination import paginate, paginate_pages
+
+__all__ = [
+    "TweetAPI",
+    "TweetAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+    "paginate",
+    "paginate_pages",
+]
+
+__version__ = "1.1.0"

tweetapi/client.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Optional, Union
+
+import requests
+
+from .errors import (
+    TweetAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    ConnectionError_,
+)
+
+
+class TweetAPI:
+    """TweetAPI Python SDK client.
+
+    Args:
+        api_key: Your TweetAPI API key.
+        base_url: Base URL for the API (default: https://api.tweetapi.com).
+        timeout: Request timeout in seconds. Pass a tuple ``(connect, read)`` for
+            split timeouts. Default: ``(10, 30)``.
+        connect_timeout: Connection timeout in seconds (used when *timeout* is not set).
+        read_timeout: Read timeout in seconds (used when *timeout* is not set).
+        max_retries: Maximum retry attempts on transient errors (default: 3, set 0 to disable).
+        backoff_multiplier: Multiplier for exponential backoff (default: 2.0).
+        initial_retry_delay: Initial retry delay in seconds (default: 1.0).
+        max_retry_delay: Maximum retry delay cap in seconds (default: 30.0).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.tweetapi.com",
+        timeout: Optional[Union[float, tuple[float, float]]] = None,
+        connect_timeout: Optional[float] = None,
+        read_timeout: Optional[float] = None,
+        max_retries: int = 3,
+        backoff_multiplier: float = 2.0,
+        initial_retry_delay: float = 1.0,
+        max_retry_delay: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("TweetAPI: api_key is required")
+
+        self._base_url = base_url.rstrip("/")
+
+        # Timeout resolution
+        if timeout is not None:
+            self._timeout: Union[float, tuple[float, float]] = timeout
+        elif connect_timeout is not None or read_timeout is not None:
+            self._timeout = (
+                connect_timeout if connect_timeout is not None else 10.0,
+                read_timeout if read_timeout is not None else 30.0,
+            )
+        else:
+            self._timeout = (10.0, 30.0)
+
+        # Retry configuration
+        self._max_retries = max_retries
+        self._backoff_multiplier = backoff_multiplier
+        self._initial_retry_delay = initial_retry_delay
+        self._max_retry_delay = max_retry_delay
+        self._rate_limit_info: Optional[dict[str, Any]] = None
+
+        self._session = requests.Session()
+        self._session.headers.update({"X-API-Key": api_key})
+
+        # Lazy imports to avoid circular dependencies
+        from .resources.user import UserResource
+        from .resources.tweet import TweetResource
+        from .resources.post import PostResource
+        from .resources.interaction import InteractionResource
+        from .resources.list_ import ListResource
+        from .resources.community import CommunityResource
+        from .resources.space import SpaceResource
+        from .resources.explore import ExploreResource
+        from .resources.auth import AuthResource
+        from .resources.xchat import XChatResource
+        from .resources.unencrypted_dm import UnencryptedDMResource
+
+        self.user = UserResource(self)
+        self.tweet = TweetResource(self)
+        self.post = PostResource(self)
+        self.interaction = InteractionResource(self)
+        self.list = ListResource(self)
+        self.community = CommunityResource(self)
+        self.space = SpaceResource(self)
+        self.explore = ExploreResource(self)
+        self.auth = AuthResource(self)
+        self.xchat = XChatResource(self)
+        self.dm = UnencryptedDMResource(self)
+
+    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """Send a GET request to the API."""
+        clean_params = None
+        if params:
+            clean_params = {
+                k: v for k, v in params.items() if v is not None
+            }
+        return self._request("GET", path, params=clean_params)
+
+    def _post(self, path: str, body: Optional[dict[str, Any]] = None) -> Any:
+        """Send a POST request to the API."""
+        clean_body = None
+        if body:
+            clean_body = {k: v for k, v in body.items() if v is not None}
+        return self._request("POST", path, json=clean_body)
+
+    @property
+    def rate_limit_info(self) -> Optional[dict[str, Any]]:
+        """Last known rate limit info from a 429 response, or ``None``."""
+        return self._rate_limit_info
+
+    # ── internal helpers ─────────────────────────────────────────────────
+
+    @property
+    def _timeout_desc(self) -> str:
+        if isinstance(self._timeout, tuple):
+            return f"connect={self._timeout[0]}s, read={self._timeout[1]}s"
+        return f"{self._timeout}s"
+
+    def _is_retryable(self, error: TweetAPIError) -> bool:
+        if isinstance(error, ConnectionError_):
+            return True
+        return error.status_code == 429 or error.status_code >= 500
+
+    def _calculate_retry_delay(self, error: Optional[TweetAPIError], attempt: int) -> float:
+        if isinstance(error, RateLimitError) and error.retry_after > 0:
+            return min(float(error.retry_after), self._max_retry_delay)
+        base = self._initial_retry_delay * (self._backoff_multiplier ** attempt)
+        capped = min(base, self._max_retry_delay)
+        return capped + random.random() * capped * 0.25
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        last_error: Optional[TweetAPIError] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._session.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    timeout=self._timeout,
+                )
+            except requests.exceptions.Timeout as e:
+                last_error = ConnectionError_(
+                    f"Request timed out ({self._timeout_desc})", e
+                )
+                if attempt < self._max_retries:
+                    time.sleep(self._calculate_retry_delay(last_error, attempt))
+                    continue
+                raise last_error from e
+            except requests.exceptions.ConnectionError as e:
+                last_error = ConnectionError_(f"Network error: {e}", e)
+                if attempt < self._max_retries:
+                    time.sleep(self._calculate_retry_delay(last_error, attempt))
+                    continue
+                raise last_error from e
+            except requests.exceptions.RequestException as e:
+                last_error = ConnectionError_(f"Request failed: {e}", e)
+                if attempt < self._max_retries:
+                    time.sleep(self._calculate_retry_delay(last_error, attempt))
+                    continue
+                raise last_error from e
+
+            if not response.ok:
+                try:
+                    self._handle_error_response(response)
+                except TweetAPIError as err:
+                    last_error = err
+                    if isinstance(err, RateLimitError):
+                        self._rate_limit_info = {
+                            "retry_after": err.retry_after,
+                            "timestamp": time.time(),
+                        }
+                    if attempt < self._max_retries and self._is_retryable(err):
+                        time.sleep(self._calculate_retry_delay(err, attempt))
+                        continue
+                    raise
+
+            return response.json()
+
+        raise last_error  # type: ignore[misc]
+
+    def _handle_error_response(self, response: requests.Response) -> None:
+        """Parse error response and raise the appropriate exception."""
+        try:
+            body = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError):
+            body = None
+
+        code = "UNKNOWN_ERROR"
+        message = f"HTTP {response.status_code}"
+        details = None
+
+        if body and isinstance(body.get("error"), dict):
+            error = body["error"]
+            code = error.get("code", code)
+            message = error.get("message", message)
+            details = error.get("details")
+
+        status = response.status_code
+
+        if status == 400:
+            raise ValidationError(message, code, details)
+        elif status == 401:
+            raise AuthenticationError(message, code, details)
+        elif status == 403:
+            raise ForbiddenError(message, code, details)
+        elif status == 404:
+            raise NotFoundError(message, code, details)
+        elif status == 429:
+            raise RateLimitError(message, code, details)
+        elif status >= 500:
+            raise ServerError(message, code, status, details)
+        else:
+            raise TweetAPIError(message, code, status, details)

tweetapi/errors.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class TweetAPIError(Exception):
+    """Base error for all TweetAPI errors.
+
+    Contains the API error code, HTTP status, and optional details.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r}, status_code={self.status_code}, message={self.message!r})"
+
+
+class AuthenticationError(TweetAPIError):
+    """Thrown when the API key or auth token is invalid or missing (HTTP 401)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 401, details)
+
+
+class ForbiddenError(TweetAPIError):
+    """Thrown when the request is forbidden (HTTP 403)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 403, details)
+
+
+class NotFoundError(TweetAPIError):
+    """Thrown when the requested resource is not found (HTTP 404)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 404, details)
+
+
+class ValidationError(TweetAPIError):
+    """Thrown when the request parameters are invalid (HTTP 400)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 400, details)
+
+
+class RateLimitError(TweetAPIError):
+    """Thrown when you've exceeded rate limits (HTTP 429).
+
+    Check ``retry_after`` for seconds until you can retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 429, details)
+        self.retry_after: int = (details or {}).get("retryAfter", 60)
+
+
+class ServerError(TweetAPIError):
+    """Thrown when the API encounters a server error (HTTP 5xx)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, status_code, details)
+
+
+class ConnectionError_(TweetAPIError):
+    """Thrown when a network error occurs (DNS failure, timeout, connection refused).
+
+    Named ``ConnectionError_`` to avoid shadowing the built-in ``ConnectionError``.
+    Also importable as ``NetworkError``.
+    """
+
+    def __init__(self, message: str, cause: Optional[Exception] = None) -> None:
+        super().__init__(message, "CONNECTION_ERROR", 0, None)
+        self.__cause__ = cause
+
+
+# Alias for cleaner imports
+NetworkError = ConnectionError_

tweetapi/pagination.py

@@ -0,0 +1,64 @@
+"""Auto-pagination helpers for cursor-based paginated endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Generator, Optional
+
+
+def paginate_pages(
+    fetcher: Callable[[Optional[str]], dict[str, Any]],
+    *,
+    max_pages: Optional[int] = None,
+) -> Generator[dict[str, Any], None, None]:
+    """Yield each full page (response dict) from a paginated endpoint.
+
+    Args:
+        fetcher: A callable that takes an optional cursor string and returns
+            a paginated response dict with ``data`` and ``pagination`` keys.
+        max_pages: Stop after this many pages. ``None`` means fetch all.
+
+    Example::
+
+        for page in paginate_pages(
+            lambda cursor: client.user.get_followers(user_id="123", cursor=cursor),
+        ):
+            print(f"Got {len(page['data'])} users")
+    """
+    cursor: Optional[str] = None
+    count = 0
+
+    while True:
+        page = fetcher(cursor)
+        yield page
+        count += 1
+
+        if max_pages is not None and count >= max_pages:
+            break
+
+        cursor = page.get("pagination", {}).get("nextCursor")
+        if not cursor:
+            break
+
+
+def paginate(
+    fetcher: Callable[[Optional[str]], dict[str, Any]],
+    *,
+    max_pages: Optional[int] = None,
+) -> Generator[Any, None, None]:
+    """Yield individual items from all pages of a paginated endpoint.
+
+    Args:
+        fetcher: A callable that takes an optional cursor string and returns
+            a paginated response dict.
+        max_pages: Stop after this many pages. ``None`` means fetch all.
+
+    Example::
+
+        for user in paginate(
+            lambda cursor: client.user.get_followers(user_id="123", cursor=cursor),
+            max_pages=5,
+        ):
+            print(user["username"])
+    """
+    for page in paginate_pages(fetcher, max_pages=max_pages):
+        yield from page.get("data", [])

tweetapi/resources/auth.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+    from ..types import LoginApiResponse
+
+
+class AuthResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def login(self, *, username: str, password: str, proxy: str, two_factor_secret: Optional[str] = None) -> LoginApiResponse:
+        """Log in to a Twitter account and get auth tokens."""
+        return self._client._post("/tw-v2/auth/login", {
+            "username": username, "password": password,
+            "proxy": proxy, "twoFactorSecret": two_factor_secret,
+        })

tweetapi/resources/community.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+    from ..types import (
+        ActionResponse,
+        CommunityResponse,
+        CommunityMemberPaginatedResponse,
+        CommunitySearchPaginatedResponse,
+        TweetsPaginatedResponse,
+    )
+
+
+class CommunityResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_details(self, *, community_id: str) -> CommunityResponse:
+        """Get community details."""
+        return self._client._get("/tw-v2/community/details", {"communityId": community_id})
+
+    def get_tweets(self, *, community_id: str, sort_by: str, cursor: Optional[str] = None) -> TweetsPaginatedResponse:
+        """Get tweets in a community."""
+        return self._client._get("/tw-v2/community/tweets", {"communityId": community_id, "sortBy": sort_by, "cursor": cursor})
+
+    def get_members(self, *, community_id: str, cursor: Optional[str] = None) -> CommunityMemberPaginatedResponse:
+        """Get community members."""
+        return self._client._get("/tw-v2/community/members", {"communityId": community_id, "cursor": cursor})
+
+    def search(self, *, query: str, cursor: Optional[str] = None) -> CommunitySearchPaginatedResponse:
+        """Search communities."""
+        return self._client._get("/tw-v2/community/search", {"query": query, "cursor": cursor})
+
+    def create_post(self, *, auth_token: str, text: str, community_id: str, proxy: str, disable_link_preview: Optional[bool] = None) -> ActionResponse:
+        """Create a post in a community."""
+        return self._client._post("/tw-v2/interaction/create-community-post", {
+            "authToken": auth_token, "text": text, "communityId": community_id,
+            "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def create_post_with_media(self, *, auth_token: str, text: str, community_id: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> ActionResponse:
+        """Create a post with media in a community."""
+        return self._client._post("/tw-v2/interaction/create-community-post-with-media", {
+            "authToken": auth_token, "text": text, "communityId": community_id,
+            "media": media, "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post(self, *, auth_token: str, text: str, tweet_id: str, community_id: str, proxy: str, disable_link_preview: Optional[bool] = None) -> ActionResponse:
+        """Reply to a community post."""
+        return self._client._post("/tw-v2/interaction/reply-community-post", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "communityId": community_id, "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post_with_media(self, *, auth_token: str, text: str, tweet_id: str, community_id: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> ActionResponse:
+        """Reply to a community post with media."""
+        return self._client._post("/tw-v2/interaction/reply-community-post-with-media", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "communityId": community_id, "media": media, "proxy": proxy,
+            "disableLinkPreview": disable_link_preview,
+        })
+
+    def join(self, *, auth_token: str, community_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Join a community."""
+        return self._client._post("/tw-v2/interaction/join-community", {
+            "authToken": auth_token, "communityId": community_id, "proxy": proxy,
+        })
+
+    def leave(self, *, auth_token: str, community_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Leave a community."""
+        return self._client._post("/tw-v2/interaction/leave-community", {
+            "authToken": auth_token, "communityId": community_id, "proxy": proxy,
+        })

tweetapi/resources/explore.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+    from ..types import SearchResponse
+
+
+class ExploreResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def search(self, *, query: str, type: str, cursor: Optional[str] = None) -> SearchResponse:
+        """Search for tweets, users, photos, or videos.
+
+        Args:
+            query: Search query string. Supports Twitter search operators.
+            type: Type of search results — "Latest", "Top", "People", "Photos", or "Videos".
+            cursor: Pagination cursor for fetching next page.
+        """
+        return self._client._get("/tw-v2/search", {"query": query, "type": type, "cursor": cursor})

tweetapi/resources/interaction.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+    from ..types import (
+        ActionResponse,
+        NotificationPaginatedResponse,
+        UserAnalyticsResponse,
+    )
+
+
+class InteractionResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def favorite_post(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Like a tweet."""
+        return self._client._post("/tw-v2/interaction/like-post", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def unfavorite_post(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Unlike a tweet."""
+        return self._client._post("/tw-v2/interaction/unlike-post", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def retweet(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Retweet a tweet."""
+        return self._client._post("/tw-v2/interaction/retweet", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def delete_retweet(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Remove a retweet."""
+        return self._client._post("/tw-v2/interaction/delete-retweet", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def bookmark(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Bookmark a tweet."""
+        return self._client._post("/tw-v2/interaction/bookmark", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def delete_bookmark(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Remove a bookmark."""
+        return self._client._post("/tw-v2/interaction/delete-bookmark", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def follow(self, *, auth_token: str, user_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Follow a user."""
+        return self._client._post("/tw-v2/interaction/follow", {
+            "authToken": auth_token, "userId": user_id, "proxy": proxy,
+        })
+
+    def unfollow(self, *, auth_token: str, user_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Unfollow a user."""
+        return self._client._post("/tw-v2/interaction/unfollow", {
+            "authToken": auth_token, "userId": user_id, "proxy": proxy,
+        })
+
+    def add_member_to_list(self, *, auth_token: str, list_id: str, user_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Add a user to a list."""
+        return self._client._post("/tw-v2/interaction/add-to-list", {
+            "authToken": auth_token, "listId": list_id, "userId": user_id, "proxy": proxy,
+        })
+
+    def remove_member_from_list(self, *, auth_token: str, list_id: str, user_id: str, proxy: Optional[str] = None) -> ActionResponse:
+        """Remove a user from a list."""
+        return self._client._post("/tw-v2/interaction/remove-from-list", {
+            "authToken": auth_token, "listId": list_id, "userId": user_id, "proxy": proxy,
+        })
+
+    def get_notifications(self, *, auth_token: str, timeline_type: Optional[str] = None, count: Optional[int] = None, cursor: Optional[str] = None, proxy: Optional[str] = None) -> NotificationPaginatedResponse:
+        """Get your notifications."""
+        return self._client._get("/tw-v2/interaction/notifications", {
+            "authToken": auth_token, "timelineType": timeline_type,
+            "count": count, "cursor": cursor, "proxy": proxy,
+        })
+
+    def get_user_analytics(self, *, auth_token: str, to_time: Optional[str] = None, from_time: Optional[str] = None, granularity: Optional[str] = None, show_verified_followers: Optional[bool] = None, proxy: Optional[str] = None) -> UserAnalyticsResponse:
+        """Get your account analytics."""
+        return self._client._get("/tw-v2/interaction/user-analytics", {
+            "authToken": auth_token, "toTime": to_time, "fromTime": from_time,
+            "granularity": granularity, "showVerifiedFollowers": show_verified_followers,
+            "proxy": proxy,
+        })