xdataapi 0.3.0__py3-none-any.whl

xdataapi/client.py

@@ -0,0 +1,268 @@
+import ssl
+from typing import Any, Self
+
+import httpx
+from attrs import define, evolve, field
+
+
+@define
+class Client:
+    """A class for keeping track of data related to the API
+
+    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
+
+        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
+
+        ``cookies``: A dictionary of cookies to be sent with every request
+
+        ``headers``: A dictionary of headers to be sent with every request
+
+        ``timeout``: The maximum amount of a time a request can take. API functions will raise
+        httpx.TimeoutException if this is exceeded.
+
+        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
+        but can be set to False for testing purposes.
+
+        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
+
+        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
+
+
+    Attributes:
+        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
+            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
+            argument to the constructor.
+    """
+
+    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
+    _base_url: str = field(alias="base_url")
+    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
+    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
+    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
+    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
+    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
+    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
+    _client: httpx.Client | None = field(default=None, init=False)
+    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
+
+    def with_headers(self, headers: dict[str, str]) -> "Client":
+        """Get a new client matching this one with additional headers"""
+        if self._client is not None:
+            self._client.headers.update(headers)
+        if self._async_client is not None:
+            self._async_client.headers.update(headers)
+        return evolve(self, headers={**self._headers, **headers})
+
+    def with_cookies(self, cookies: dict[str, str]) -> "Client":
+        """Get a new client matching this one with additional cookies"""
+        if self._client is not None:
+            self._client.cookies.update(cookies)
+        if self._async_client is not None:
+            self._async_client.cookies.update(cookies)
+        return evolve(self, cookies={**self._cookies, **cookies})
+
+    def with_timeout(self, timeout: httpx.Timeout) -> "Client":
+        """Get a new client matching this one with a new timeout configuration"""
+        if self._client is not None:
+            self._client.timeout = timeout
+        if self._async_client is not None:
+            self._async_client.timeout = timeout
+        return evolve(self, timeout=timeout)
+
+    def set_httpx_client(self, client: httpx.Client) -> Self:
+        """Manually set the underlying httpx.Client
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._client = client
+        return self
+
+    def get_httpx_client(self) -> httpx.Client:
+        """Get the underlying httpx.Client, constructing a new one if not previously set"""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._client
+
+    def __enter__(self) -> Self:
+        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
+        self.get_httpx_client().__enter__()
+        return self
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for internal httpx.Client (see httpx docs)"""
+        self.get_httpx_client().__exit__(*args, **kwargs)
+
+    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> Self:
+        """Manually set the underlying httpx.AsyncClient
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._async_client = async_client
+        return self
+
+    def get_async_httpx_client(self) -> httpx.AsyncClient:
+        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._async_client
+
+    async def __aenter__(self) -> Self:
+        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
+        await self.get_async_httpx_client().__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
+        await self.get_async_httpx_client().__aexit__(*args, **kwargs)
+
+
+@define
+class AuthenticatedClient:
+    """A Client which has been authenticated for use on secured endpoints
+
+    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
+
+        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
+
+        ``cookies``: A dictionary of cookies to be sent with every request
+
+        ``headers``: A dictionary of headers to be sent with every request
+
+        ``timeout``: The maximum amount of a time a request can take. API functions will raise
+        httpx.TimeoutException if this is exceeded.
+
+        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
+        but can be set to False for testing purposes.
+
+        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
+
+        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
+
+
+    Attributes:
+        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
+            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
+            argument to the constructor.
+        token: The token to use for authentication
+        prefix: The prefix to use for the Authorization header
+        auth_header_name: The name of the Authorization header
+    """
+
+    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
+    _base_url: str = field(alias="base_url")
+    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
+    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
+    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
+    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
+    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
+    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
+    _client: httpx.Client | None = field(default=None, init=False)
+    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
+
+    token: str
+    prefix: str = "Bearer"
+    auth_header_name: str = "Authorization"
+
+    def with_headers(self, headers: dict[str, str]) -> "AuthenticatedClient":
+        """Get a new client matching this one with additional headers"""
+        if self._client is not None:
+            self._client.headers.update(headers)
+        if self._async_client is not None:
+            self._async_client.headers.update(headers)
+        return evolve(self, headers={**self._headers, **headers})
+
+    def with_cookies(self, cookies: dict[str, str]) -> "AuthenticatedClient":
+        """Get a new client matching this one with additional cookies"""
+        if self._client is not None:
+            self._client.cookies.update(cookies)
+        if self._async_client is not None:
+            self._async_client.cookies.update(cookies)
+        return evolve(self, cookies={**self._cookies, **cookies})
+
+    def with_timeout(self, timeout: httpx.Timeout) -> "AuthenticatedClient":
+        """Get a new client matching this one with a new timeout configuration"""
+        if self._client is not None:
+            self._client.timeout = timeout
+        if self._async_client is not None:
+            self._async_client.timeout = timeout
+        return evolve(self, timeout=timeout)
+
+    def set_httpx_client(self, client: httpx.Client) -> Self:
+        """Manually set the underlying httpx.Client
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._client = client
+        return self
+
+    def get_httpx_client(self) -> httpx.Client:
+        """Get the underlying httpx.Client, constructing a new one if not previously set"""
+        if self._client is None:
+            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._client
+
+    def __enter__(self) -> Self:
+        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
+        self.get_httpx_client().__enter__()
+        return self
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for internal httpx.Client (see httpx docs)"""
+        self.get_httpx_client().__exit__(*args, **kwargs)
+
+    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> Self:
+        """Manually set the underlying httpx.AsyncClient
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._async_client = async_client
+        return self
+
+    def get_async_httpx_client(self) -> httpx.AsyncClient:
+        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
+        if self._async_client is None:
+            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._async_client
+
+    async def __aenter__(self) -> Self:
+        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
+        await self.get_async_httpx_client().__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
+        await self.get_async_httpx_client().__aexit__(*args, **kwargs)

xdataapi/errors.py

@@ -0,0 +1,16 @@
+"""Contains shared errors types that can be raised from API functions"""
+
+
+class UnexpectedStatus(Exception):
+    """Raised by api functions when the response status an undocumented status and Client.raise_on_unexpected_status is True"""
+
+    def __init__(self, status_code: int, content: bytes):
+        self.status_code = status_code
+        self.content = content
+
+        super().__init__(
+            f"Unexpected status code: {status_code}\n\nResponse content:\n{content.decode(errors='ignore')}"
+        )
+
+
+__all__ = ["UnexpectedStatus"]

xdataapi/models/__init__.py

@@ -0,0 +1,67 @@
+"""Contains all the data models used in inputs/outputs"""
+
+from .batch_error import BatchError
+from .batch_error_code import BatchErrorCode
+from .batch_meta import BatchMeta
+from .batch_meta_cache import BatchMetaCache
+from .create_checkout_body import CreateCheckoutBody
+from .create_checkout_body_pack import CreateCheckoutBodyPack
+from .create_checkout_response_200 import CreateCheckoutResponse200
+from .error import Error
+from .error_body import ErrorBody
+from .error_body_code import ErrorBodyCode
+from .get_me_response_200 import GetMeResponse200
+from .get_tweets_body import GetTweetsBody
+from .get_users_body import GetUsersBody
+from .id_page import IdPage
+from .list_packs_response_200 import ListPacksResponse200
+from .list_packs_response_200_data_item import ListPacksResponse200DataItem
+from .list_packs_response_200_rate_limits_item import ListPacksResponse200RateLimitsItem
+from .media import Media
+from .media_type import MediaType
+from .meta import Meta
+from .meta_cache import MetaCache
+from .problem import Problem
+from .search_tweets_product import SearchTweetsProduct
+from .tweet import Tweet
+from .tweet_batch import TweetBatch
+from .tweet_page import TweetPage
+from .tweet_response import TweetResponse
+from .user import User
+from .user_batch import UserBatch
+from .user_page import UserPage
+from .user_response import UserResponse
+
+__all__ = (
+    "BatchError",
+    "BatchErrorCode",
+    "BatchMeta",
+    "BatchMetaCache",
+    "CreateCheckoutBody",
+    "CreateCheckoutBodyPack",
+    "CreateCheckoutResponse200",
+    "Error",
+    "ErrorBody",
+    "ErrorBodyCode",
+    "GetMeResponse200",
+    "GetTweetsBody",
+    "GetUsersBody",
+    "IdPage",
+    "ListPacksResponse200",
+    "ListPacksResponse200DataItem",
+    "ListPacksResponse200RateLimitsItem",
+    "Media",
+    "MediaType",
+    "Meta",
+    "MetaCache",
+    "Problem",
+    "SearchTweetsProduct",
+    "Tweet",
+    "TweetBatch",
+    "TweetPage",
+    "TweetResponse",
+    "User",
+    "UserBatch",
+    "UserPage",
+    "UserResponse",
+)

xdataapi/models/batch_error.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..models.batch_error_code import BatchErrorCode
+
+T = TypeVar("T", bound="BatchError")
+
+
+@_attrs_define
+class BatchError:
+    """
+    Attributes:
+        input_ (str): The handle or id as sent.
+        code (BatchErrorCode):
+        message (str):
+    """
+
+    input_: str
+    code: BatchErrorCode
+    message: str
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        input_ = self.input_
+
+        code = self.code.value
+
+        message = self.message
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "input": input_,
+                "code": code,
+                "message": message,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        input_ = d.pop("input")
+
+        code = BatchErrorCode(d.pop("code"))
+
+        message = d.pop("message")
+
+        batch_error = cls(
+            input_=input_,
+            code=code,
+            message=message,
+        )
+
+        batch_error.additional_properties = d
+        return batch_error
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

xdataapi/models/batch_error_code.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class BatchErrorCode(StrEnum):
+    ACCESS_DENIED = "access_denied"
+    BAD_REQUEST = "bad_request"
+    NOT_FOUND = "not_found"
+    NO_ACCOUNT = "no_account"
+    NO_CREDITS = "no_credits"
+    REQUEST_REJECTED = "request_rejected"
+    UPSTREAM_ERROR = "upstream_error"
+    UPSTREAM_RATE_LIMITED = "upstream_rate_limited"
+
+    def __str__(self) -> str:
+        return str(self.value)

xdataapi/models/batch_meta.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, TypeVar
+from uuid import UUID
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..models.batch_meta_cache import BatchMetaCache
+
+if TYPE_CHECKING:
+    from ..models.batch_error import BatchError
+
+
+T = TypeVar("T", bound="BatchMeta")
+
+
+@_attrs_define
+class BatchMeta:
+    """
+    Attributes:
+        errors (list[BatchError]): Inputs that returned nothing, with the reason. Never charged.
+        items (int): Objects returned.
+        credits_charged (float):
+        balance_remaining (float):
+        cache (BatchMetaCache):
+        cache_hits (int): Objects served from cache
+        request_id (UUID):
+    """
+
+    errors: list[BatchError]
+    items: int
+    credits_charged: float
+    balance_remaining: float
+    cache: BatchMetaCache
+    cache_hits: int
+    request_id: UUID
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        errors = []
+        for errors_item_data in self.errors:
+            errors_item = errors_item_data.to_dict()
+            errors.append(errors_item)
+
+        items = self.items
+
+        credits_charged = self.credits_charged
+
+        balance_remaining = self.balance_remaining
+
+        cache = self.cache.value
+
+        cache_hits = self.cache_hits
+
+        request_id = str(self.request_id)
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "errors": errors,
+                "items": items,
+                "credits_charged": credits_charged,
+                "balance_remaining": balance_remaining,
+                "cache": cache,
+                "cache_hits": cache_hits,
+                "request_id": request_id,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        from ..models.batch_error import BatchError  # noqa: PLC0415
+
+        d = dict(src_dict)
+        errors = []
+        _errors = d.pop("errors")
+        for errors_item_data in _errors:
+            errors_item = BatchError.from_dict(errors_item_data)
+
+            errors.append(errors_item)
+
+        items = d.pop("items")
+
+        credits_charged = d.pop("credits_charged")
+
+        balance_remaining = d.pop("balance_remaining")
+
+        cache = BatchMetaCache(d.pop("cache"))
+
+        cache_hits = d.pop("cache_hits")
+
+        request_id = UUID(d.pop("request_id"))
+
+        batch_meta = cls(
+            errors=errors,
+            items=items,
+            credits_charged=credits_charged,
+            balance_remaining=balance_remaining,
+            cache=cache,
+            cache_hits=cache_hits,
+            request_id=request_id,
+        )
+
+        batch_meta.additional_properties = d
+        return batch_meta
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

xdataapi/models/batch_meta_cache.py

@@ -0,0 +1,11 @@
+from enum import StrEnum
+
+
+class BatchMetaCache(StrEnum):
+    BYPASS = "bypass"
+    HIT = "hit"
+    MISS = "miss"
+    MIXED = "mixed"
+
+    def __str__(self) -> str:
+        return str(self.value)

xdataapi/models/create_checkout_body.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..models.create_checkout_body_pack import CreateCheckoutBodyPack
+
+T = TypeVar("T", bound="CreateCheckoutBody")
+
+
+@_attrs_define
+class CreateCheckoutBody:
+    """
+    Attributes:
+        pack (CreateCheckoutBodyPack):
+    """
+
+    pack: CreateCheckoutBodyPack
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        pack = self.pack.value
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "pack": pack,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        pack = CreateCheckoutBodyPack(d.pop("pack"))
+
+        create_checkout_body = cls(
+            pack=pack,
+        )
+
+        create_checkout_body.additional_properties = d
+        return create_checkout_body
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

xdataapi/models/create_checkout_body_pack.py

@@ -0,0 +1,11 @@
+from enum import StrEnum
+
+
+class CreateCheckoutBodyPack(StrEnum):
+    BUILDER = "builder"
+    GROWTH = "growth"
+    SCALE = "scale"
+    STARTER = "starter"
+
+    def __str__(self) -> str:
+        return str(self.value)