twittrapi 0.2.0__py3-none-any.whl

twittrapi/__init__.py

@@ -0,0 +1,55 @@
+"""Official Python client for TwittrAPI (https://twittrapi.com), a read API for X (Twitter) data.
+
+    from twittrapi import TwittrAPI
+
+    client = TwittrAPI(api_key="...")
+    user = client.users.get_by_username("jack")
+
+    # Compact, camelCase JSON instead of X's raw GraphQL (opt-in, per client or per call):
+    simple = TwittrAPI(api_key="...", response_format="simple")
+    user = client.users.get_by_username("jack", response_format="simple")
+
+Not affiliated with X Corp.
+"""
+
+from ._base import DEFAULT_BASE_URL, RAPIDAPI_BASE_URL, RAPIDAPI_HOST, ResponseFormat
+from ._client import DEFAULT_MAX_PAGES, AsyncTwittrAPI, TwittrAPI
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TwittrAPIError,
+    ValidationError,
+)
+from ._endpoints import MAX_COUNT
+from ._version import __version__
+from .pagination import extract_bottom_cursor, simple_next_cursor
+
+__all__ = [
+    "__version__",
+    "TwittrAPI",
+    "AsyncTwittrAPI",
+    "TwittrAPIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "ValidationError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "extract_bottom_cursor",
+    "simple_next_cursor",
+    "ResponseFormat",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_PAGES",
+    "MAX_COUNT",
+    "RAPIDAPI_BASE_URL",
+    "RAPIDAPI_HOST",
+]

twittrapi/_base.py

@@ -0,0 +1,272 @@
+"""Shared logic for the sync and async clients: configuration, request building, error
+mapping and retry timing. Nothing in here does I/O."""
+
+from __future__ import annotations
+
+import email.utils
+import json
+import os
+import random
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Literal, Mapping, Optional, Union, cast
+
+import httpx
+
+from ._endpoints import QueryValue
+from ._exceptions import (
+    APIStatusError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TwittrAPIError,
+    ValidationError,
+)
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.twittrapi.com"
+RAPIDAPI_HOST = "twitter-aio.p.rapidapi.com"
+RAPIDAPI_BASE_URL = f"https://{RAPIDAPI_HOST}"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+# Backoff for retries without a Retry-After header: 0.5s, 1s, 2s, ... capped, plus jitter.
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0
+# Upper bound for honoring a server-sent Retry-After, so a bad header cannot stall a script.
+MAX_RETRY_AFTER = 60.0
+
+ENV_API_KEY = "TWITTRAPI_API_KEY"
+ENV_RAPIDAPI_KEY = "RAPIDAPI_KEY"
+ENV_BASE_URL = "TWITTRAPI_BASE_URL"
+
+USER_AGENT = f"twittrapi-python/{__version__}"
+
+TimeoutTypes = Union[float, httpx.Timeout, None]
+
+ResponseFormat = Literal["raw", "simple"]
+"""``"raw"``: X's JSON exactly as X sends it (the default). ``"simple"``: the API's compact,
+camelCase format (``format=simple``), see https://twittrapi.com/docs/simple-format."""
+
+RESPONSE_FORMATS = ("raw", "simple")
+DEFAULT_RESPONSE_FORMAT: ResponseFormat = "raw"
+FORMAT_PARAM = "format"
+
+
+def check_response_format(value: Any, name: str = "response_format") -> ResponseFormat:
+    if value not in RESPONSE_FORMATS:
+        raise ValueError(f"{name} must be \"raw\" or \"simple\", got {value!r}")
+    return cast(ResponseFormat, value)
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    mode: str  # "direct" or "rapidapi"
+    api_key: str
+    base_url: str
+
+    @property
+    def is_rapidapi(self) -> bool:
+        return self.mode == "rapidapi"
+
+
+def _clean(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def resolve_config(
+    api_key: Optional[str],
+    rapidapi_key: Optional[str],
+    base_url: Optional[str],
+    env: Optional[Mapping[str, str]] = None,
+) -> ClientConfig:
+    """Picks the auth mode. Explicit arguments win over environment variables; within each,
+    the direct key wins over the RapidAPI key."""
+    env = os.environ if env is None else env
+    api_key = _clean(api_key)
+    rapidapi_key = _clean(rapidapi_key)
+
+    if api_key and rapidapi_key:
+        raise ValueError("Pass either api_key or rapidapi_key, not both.")
+
+    mode: Optional[str] = None
+    key: Optional[str] = None
+    if api_key:
+        mode, key = "direct", api_key
+    elif rapidapi_key:
+        mode, key = "rapidapi", rapidapi_key
+    elif _clean(env.get(ENV_API_KEY)):
+        mode, key = "direct", _clean(env.get(ENV_API_KEY))
+    elif _clean(env.get(ENV_RAPIDAPI_KEY)):
+        mode, key = "rapidapi", _clean(env.get(ENV_RAPIDAPI_KEY))
+
+    if not mode or not key:
+        raise TwittrAPIError(
+            "No API key found. Pass api_key=... (direct API, get one at https://twittrapi.com) "
+            "or rapidapi_key=... (RapidAPI), or set the TWITTRAPI_API_KEY or RAPIDAPI_KEY "
+            "environment variable."
+        )
+
+    url = _clean(base_url)
+    if url is None and mode == "direct":
+        url = _clean(env.get(ENV_BASE_URL))
+    if url is None:
+        url = RAPIDAPI_BASE_URL if mode == "rapidapi" else DEFAULT_BASE_URL
+    return ClientConfig(mode=mode, api_key=key, base_url=url.rstrip("/"))
+
+
+def build_headers(config: ClientConfig) -> Dict[str, str]:
+    headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+    if config.is_rapidapi:
+        headers["x-rapidapi-key"] = config.api_key
+        headers["x-rapidapi-host"] = RAPIDAPI_HOST
+    else:
+        headers["X-API-KEY"] = config.api_key
+    return headers
+
+
+def build_url(config: ClientConfig, path: str) -> str:
+    return config.base_url + (path if path.startswith("/") else "/" + path)
+
+
+def clean_params(params: Mapping[str, Optional[QueryValue]]) -> Dict[str, QueryValue]:
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def format_params(
+    params: Dict[str, QueryValue], response_format: ResponseFormat
+) -> Dict[str, QueryValue]:
+    """Adds ``format=simple`` for the simple format. Raw requests are sent exactly as before
+    (no ``format`` parameter), so their responses do not change."""
+    if response_format == "simple":
+        params = {**params, FORMAT_PARAM: "simple"}
+    return params
+
+
+def make_timeout(timeout: TimeoutTypes) -> httpx.Timeout:
+    if isinstance(timeout, httpx.Timeout):
+        return timeout
+    return httpx.Timeout(timeout)
+
+
+# ---------------------------------------------------------------------------
+# Responses and errors
+# ---------------------------------------------------------------------------
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    text = response.text
+    if not text.strip():
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _error_text(body: Any) -> Optional[str]:
+    if isinstance(body, dict):
+        for key in ("error", "message", "detail"):
+            value = body.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    if isinstance(body, str) and body.strip():
+        text = body.strip()
+        return text if len(text) <= 500 else text[:500] + "..."
+    return None
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Parses a Retry-After header given in seconds or as an HTTP date."""
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        seconds = float(value)
+    except ValueError:
+        try:
+            parsed = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError, IndexError):
+            return None
+        if parsed is None:
+            return None
+        seconds = parsed.timestamp() - time.time()
+    return max(seconds, 0.0)
+
+
+_DEFAULT_MESSAGES = {
+    400: "Bad request. Check the parameters you passed.",
+    401: "Authentication failed. Check your API key.",
+    402: "No balance left on this TwittrAPI account. Top up at https://twittrapi.com.",
+    403: "Access denied. The key may not have access to this endpoint, or X refused the request.",
+    404: "Not found. The user, tweet, list or community may not exist, be private, or be suspended.",
+    422: "Invalid input. Check the IDs and parameters you passed.",
+    429: "Rate limit hit. Wait before retrying.",
+}
+
+
+def make_status_error(response: httpx.Response) -> APIStatusError:
+    status = response.status_code
+    body = _parse_body(response)
+    detail = _error_text(body)
+    if detail:
+        message = detail
+    elif status in _DEFAULT_MESSAGES:
+        message = _DEFAULT_MESSAGES[status]
+    elif status >= 500:
+        message = "TwittrAPI or X returned a server error. This is usually temporary."
+    else:
+        message = f"Request failed with status {status}."
+
+    kwargs: Dict[str, Any] = {"status_code": status, "body": body, "response": response}
+    if status in (400, 422):
+        return ValidationError(message, **kwargs)
+    if status in (401, 403):
+        return AuthenticationError(message, **kwargs)
+    if status == 402:
+        return InsufficientBalanceError(message, **kwargs)
+    if status == 404:
+        return NotFoundError(message, **kwargs)
+    if status == 429:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        return RateLimitError(message, retry_after=retry_after, **kwargs)
+    if status >= 500:
+        return ServerError(message, **kwargs)
+    return APIStatusError(message, **kwargs)
+
+
+def process_response(response: httpx.Response) -> Any:
+    """Returns the parsed JSON body, or raises the matching exception for an error status."""
+    if response.status_code >= 400:
+        raise make_status_error(response)
+    body = _parse_body(response)
+    if isinstance(body, str):
+        raise TwittrAPIError(
+            "Expected a JSON response but got something else.",
+            status_code=response.status_code,
+            body=body,
+            response=response,
+        )
+    return body
+
+
+# ---------------------------------------------------------------------------
+# Retries
+# ---------------------------------------------------------------------------
+
+
+def should_retry_status(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+def retry_delay(attempt: int, retry_after: Optional[float] = None) -> float:
+    """Seconds to wait before retry number ``attempt + 1`` (attempt starts at 0)."""
+    if retry_after is not None:
+        return min(retry_after, MAX_RETRY_AFTER)
+    base: float = min(INITIAL_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY)
+    return base * (1 + random.uniform(0, 0.25))

twittrapi/_client.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from types import TracebackType
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    Iterator,
+    Mapping,
+    Optional,
+    Set,
+    Type,
+)
+
+import httpx
+
+from . import _base
+from ._base import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RESPONSE_FORMAT,
+    DEFAULT_TIMEOUT,
+    ClientConfig,
+    ResponseFormat,
+    TimeoutTypes,
+)
+from ._endpoints import QueryValue
+from ._exceptions import APIConnectionError, APITimeoutError, RateLimitError
+from .pagination import extract_bottom_cursor, is_simple_page, page_is_empty, simple_next_cursor
+from .resources import (
+    AsyncCommunities,
+    AsyncLists,
+    AsyncSearch,
+    AsyncTrends,
+    AsyncTweets,
+    AsyncUsers,
+    Communities,
+    Lists,
+    Search,
+    Trends,
+    Tweets,
+    Users,
+)
+
+__all__ = ["TwittrAPI", "AsyncTwittrAPI", "DEFAULT_MAX_PAGES"]
+
+DEFAULT_MAX_PAGES = 10
+
+
+def _check_max_retries(max_retries: int) -> int:
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be an integer >= 0")
+    return max_retries
+
+
+def _check_max_pages(max_pages: Optional[int]) -> None:
+    if max_pages is not None and (
+        isinstance(max_pages, bool) or not isinstance(max_pages, int) or max_pages < 1
+    ):
+        raise ValueError("max_pages must be a positive integer or None")
+
+
+def _next_page_cursor(page: Any, response_format: ResponseFormat) -> Optional[str]:
+    """The cursor to request next, or ``None`` to stop.
+
+    Simple-format pages say it themselves (``nextCursor`` / ``hasNextPage``). Raw pages, and
+    simple-format requests the API answered raw (routes without a simple format), fall back
+    to the best-effort search for X's bottom cursor.
+    """
+    if response_format == "simple" and is_simple_page(page):
+        return simple_next_cursor(page)
+    next_cursor = extract_bottom_cursor(page)
+    if not next_cursor or page_is_empty(page):
+        return None
+    return next_cursor
+
+
+class _ClientMixin:
+    _config: ClientConfig
+    max_retries: int
+    response_format: ResponseFormat
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    @property
+    def auth_mode(self) -> str:
+        """``"direct"`` (X-API-KEY header) or ``"rapidapi"`` (x-rapidapi-key header)."""
+        return self._config.mode
+
+    def _resolve_format(self, response_format: Optional[ResponseFormat]) -> ResponseFormat:
+        if response_format is None:
+            return self.response_format
+        return _base.check_response_format(response_format)
+
+    def _request_args(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Optional[QueryValue]]],
+        response_format: Optional[ResponseFormat] = None,
+    ) -> Dict[str, Any]:
+        fmt = self._resolve_format(response_format)
+        return {
+            "url": _base.build_url(self._config, path),
+            "params": _base.format_params(_base.clean_params(params or {}), fmt),
+            "headers": _base.build_headers(self._config),
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(auth_mode={self.auth_mode!r}, base_url={self.base_url!r}, "
+            f"response_format={self.response_format!r})"
+        )
+
+
+class TwittrAPI(_ClientMixin):
+    """Synchronous TwittrAPI client.
+
+    Auth: pass ``api_key`` for the direct API (https://twittrapi.com) or ``rapidapi_key`` for
+    RapidAPI. With neither, the ``TWITTRAPI_API_KEY`` and then ``RAPIDAPI_KEY`` environment
+    variables are used.
+
+    Every method returns the parsed JSON from the API. By default that is X's raw GraphQL
+    response. With ``response_format="simple"`` (here for every call, or per call on any
+    method) the API answers in its compact simple format (``{"data": ..., "nextCursor": ...,
+    "hasNextPage": ...}`` with flat, camelCase tweets and users); parse it with
+    :mod:`twittrapi.models` if you want typed objects.
+    Requests that fail with 429, 5xx or a network error are retried ``max_retries`` times
+    with exponential backoff. Other errors raise immediately.
+
+    Use it as a context manager, or call :meth:`close` when done.
+    """
+
+    users: Users
+    tweets: Tweets
+    search: Search
+    lists: Lists
+    communities: Communities
+    trends: Trends
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        rapidapi_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: TimeoutTypes = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+        response_format: ResponseFormat = DEFAULT_RESPONSE_FORMAT,
+    ) -> None:
+        self._config = _base.resolve_config(api_key, rapidapi_key, base_url)
+        self.response_format = _base.check_response_format(response_format)
+        self.max_retries = _check_max_retries(max_retries)
+        self.timeout = _base.make_timeout(timeout)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+        self._sleep: Callable[[float], None] = time.sleep
+
+        self.users = Users(self)
+        self.tweets = Tweets(self)
+        self.search = Search(self)
+        self.lists = Lists(self)
+        self.communities = Communities(self)
+        self.trends = Trends(self)
+
+    def _get(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Optional[QueryValue]]] = None,
+        *,
+        response_format: Optional[ResponseFormat] = None,
+    ) -> Any:
+        """Sends a GET request with retries and returns the parsed JSON body."""
+        args = self._request_args(path, params, response_format)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.get(timeout=self.timeout, **args)
+            except httpx.TimeoutException as exc:
+                if attempt < self.max_retries:
+                    self._sleep(_base.retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request to TwittrAPI timed out: {exc}") from exc
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    self._sleep(_base.retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Could not reach TwittrAPI: {exc}") from exc
+
+            if attempt < self.max_retries and _base.should_retry_status(response.status_code):
+                error = _base.make_status_error(response)
+                retry_after = error.retry_after if isinstance(error, RateLimitError) else None
+                self._sleep(_base.retry_delay(attempt, retry_after))
+                attempt += 1
+                continue
+            return _base.process_response(response)
+
+    def paginate(
+        self,
+        method: Callable[..., Any],
+        *args: Any,
+        max_pages: Optional[int] = DEFAULT_MAX_PAGES,
+        **kwargs: Any,
+    ) -> Iterator[Any]:
+        """Calls a paginated method repeatedly and yields each page.
+
+        ``method`` is any client method that takes ``cursor``, e.g. ``client.users.followers``.
+        Other arguments are passed through. Pass ``cursor=`` to start from a saved cursor.
+
+        In the simple format (the client's ``response_format``, or ``response_format=`` passed
+        here for this iteration) each page's ``nextCursor`` is followed until ``hasNextPage``
+        is false. In the raw format X's bottom cursor is followed; that detection is
+        best-effort, see :mod:`twittrapi.pagination`.
+
+        Stops when ``max_pages`` pages have been fetched (``None`` for no limit), when there
+        is no next cursor, when the cursor repeats, or when a page has no results. Each page
+        is a billed request.
+        """
+        _check_max_pages(max_pages)
+        cursor: Optional[str] = kwargs.pop("cursor", None)
+        fmt = self._resolve_format(kwargs.get("response_format"))
+        seen: Set[str] = set()
+        pages = 0
+        while max_pages is None or pages < max_pages:
+            page = method(*args, cursor=cursor, **kwargs)
+            pages += 1
+            yield page
+            next_cursor = _next_page_cursor(page, fmt)
+            if not next_cursor or next_cursor in seen or next_cursor == cursor:
+                return
+            seen.add(next_cursor)
+            cursor = next_cursor
+
+    def close(self) -> None:
+        """Closes the underlying HTTP client (unless you passed your own ``http_client``)."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "TwittrAPI":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+
+class AsyncTwittrAPI(_ClientMixin):
+    """Asynchronous TwittrAPI client. Same arguments and methods as :class:`TwittrAPI`, but
+    every API method is a coroutine and :meth:`paginate` is an async iterator.
+
+    Use it as an async context manager, or call ``await client.aclose()`` when done.
+    """
+
+    users: AsyncUsers
+    tweets: AsyncTweets
+    search: AsyncSearch
+    lists: AsyncLists
+    communities: AsyncCommunities
+    trends: AsyncTrends
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        rapidapi_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: TimeoutTypes = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.AsyncClient] = None,
+        response_format: ResponseFormat = DEFAULT_RESPONSE_FORMAT,
+    ) -> None:
+        self._config = _base.resolve_config(api_key, rapidapi_key, base_url)
+        self.response_format = _base.check_response_format(response_format)
+        self.max_retries = _check_max_retries(max_retries)
+        self.timeout = _base.make_timeout(timeout)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+        self._sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
+
+        self.users = AsyncUsers(self)
+        self.tweets = AsyncTweets(self)
+        self.search = AsyncSearch(self)
+        self.lists = AsyncLists(self)
+        self.communities = AsyncCommunities(self)
+        self.trends = AsyncTrends(self)
+
+    async def _get(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Optional[QueryValue]]] = None,
+        *,
+        response_format: Optional[ResponseFormat] = None,
+    ) -> Any:
+        args = self._request_args(path, params, response_format)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.get(timeout=self.timeout, **args)
+            except httpx.TimeoutException as exc:
+                if attempt < self.max_retries:
+                    await self._sleep(_base.retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request to TwittrAPI timed out: {exc}") from exc
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    await self._sleep(_base.retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Could not reach TwittrAPI: {exc}") from exc
+
+            if attempt < self.max_retries and _base.should_retry_status(response.status_code):
+                error = _base.make_status_error(response)
+                retry_after = error.retry_after if isinstance(error, RateLimitError) else None
+                await self._sleep(_base.retry_delay(attempt, retry_after))
+                attempt += 1
+                continue
+            return _base.process_response(response)
+
+    async def paginate(
+        self,
+        method: Callable[..., Awaitable[Any]],
+        *args: Any,
+        max_pages: Optional[int] = DEFAULT_MAX_PAGES,
+        **kwargs: Any,
+    ) -> AsyncIterator[Any]:
+        """Async version of :meth:`TwittrAPI.paginate`. Use with ``async for``."""
+        _check_max_pages(max_pages)
+        cursor: Optional[str] = kwargs.pop("cursor", None)
+        fmt = self._resolve_format(kwargs.get("response_format"))
+        seen: Set[str] = set()
+        pages = 0
+        while max_pages is None or pages < max_pages:
+            page = await method(*args, cursor=cursor, **kwargs)
+            pages += 1
+            yield page
+            next_cursor = _next_page_cursor(page, fmt)
+            if not next_cursor or next_cursor in seen or next_cursor == cursor:
+                return
+            seen.add(next_cursor)
+            cursor = next_cursor
+
+    async def aclose(self) -> None:
+        """Closes the underlying HTTP client (unless you passed your own ``http_client``)."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncTwittrAPI":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()