bytekit-sdk 0.3.0__py3-none-any.whl

bytekit/client.py

@@ -0,0 +1,418 @@
+import ssl
+from typing import Any, Optional, Union
+
+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.
+            Explicit constructor arguments always win over these defaults (explicit arg > default).
+    """
+
+    raise_on_unexpected_status: bool = field(default=True, kw_only=True)  # BYTEKIT-DEFAULTS
+    _base_url: str = field(default="https://api.bytekit.com", kw_only=True, 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: Optional[httpx.Timeout] = field(
+        default=httpx.Timeout(120.0), kw_only=True, alias="timeout"
+    )
+    _verify_ssl: Union[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: Optional[httpx.Client] = field(default=None, init=False)
+    _async_client: Optional[httpx.AsyncClient] = 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 (in seconds)"""
+        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) -> "Client":
+        """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) -> "Client":
+        """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) -> "Client":
+        """Manually 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) -> "Client":
+        """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.
+            Explicit constructor arguments always win over these defaults (explicit arg > default).
+        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=True, kw_only=True)  # BYTEKIT-DEFAULTS
+    _base_url: str = field(default="https://api.bytekit.com", kw_only=True, 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: Optional[httpx.Timeout] = field(
+        default=httpx.Timeout(120.0), kw_only=True, alias="timeout"
+    )
+    _verify_ssl: Union[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: Optional[httpx.Client] = field(default=None, init=False)
+    _async_client: Optional[httpx.AsyncClient] = 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 (in seconds)"""
+        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) -> "AuthenticatedClient":
+        """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) -> "AuthenticatedClient":
+        """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
+    ) -> "AuthenticatedClient":
+        """Manually 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) -> "AuthenticatedClient":
+        """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)
+
+
+# BYTEKIT-HANDWRITTEN: search convenience wrapper (injected post-generation)
+#
+# This fragment is APPENDED to the generated src/bytekit/client.py by
+# scripts/inject-handwritten.py after every regeneration. It lives here (outside
+# src/bytekit/) so `openapi-python-client generate --overwrite`, which deletes and
+# recreates the entire src/bytekit/ package, can never delete it.
+#
+# It attaches a `search()` convenience method onto the generated AuthenticatedClient
+# class (defined earlier in client.py, so it is in scope when this fragment runs).
+# Keep the body behaviorally identical to what tests/test_search.py exercises.
+
+
+def _search_unexpected(response: "httpx.Response") -> "UnexpectedStatus":
+    """Build the SDK's typed error for a non-200 search response.
+
+    Safe against non-JSON bodies: a documented status served an HTML/LB/Cloudflare
+    page (e.g. a 502) surfaces as ``UnexpectedStatus(status, raw_body)`` rather than
+    a bare ``json.JSONDecodeError``. When the body is the documented ``Error``
+    envelope (``{"error": {"code", "message"}}``) — or a flat ``{"code", "message"}``
+    dict — those fields are attached to the error. Every other shape (including the
+    masked-provider 502 ``{"error": "search_provider_error"}`` where ``error`` is a
+    STRING) falls through to a plain typed error with ``code``/``message`` = ``None``,
+    so the upstream provider's identity is never surfaced.
+    """
+    import json as _json
+
+    from . import errors
+
+    try:
+        body = response.json()
+    except (ValueError, _json.JSONDecodeError):
+        # Non-JSON documented-status body (HTML error page, load-balancer text).
+        return errors.UnexpectedStatus(response.status_code, response.content)
+
+    if isinstance(body, dict):
+        inner = body.get("error")
+        if isinstance(inner, dict) and ("code" in inner or "message" in inner):
+            return errors.UnexpectedStatus(
+                response.status_code,
+                response.content,
+                code=inner.get("code"),
+                message=inner.get("message"),
+            )
+        if "code" in body or "message" in body:
+            return errors.UnexpectedStatus(
+                response.status_code,
+                response.content,
+                code=body.get("code"),
+                message=body.get("message"),
+            )
+
+    return errors.UnexpectedStatus(response.status_code, response.content)
+
+
+def _search(
+    self,
+    query: str,
+    *,
+    type: str | None = None,
+    limit: int | None = None,
+    country: str | None = None,
+    language: str | None = None,
+    date_range: str | None = None,
+) -> "CreateSearchResponse200":
+    """Run a web search and return ranked organic results.
+
+    Convenience wrapper over the generated ``create_search`` operation: it builds
+    the request body, issues the request, and returns the parsed 200 model. Every
+    non-200 response is surfaced as ``errors.UnexpectedStatus`` carrying the raw
+    status code and (vendor-masked) response body — never a silent ``None`` and
+    never a bare ``json.JSONDecodeError`` on a non-JSON error page. When the server
+    returns the documented ``Error`` envelope, the error's ``code`` and ``message``
+    are preserved on the raised exception; the upstream provider's identity is never
+    exposed.
+
+    Args:
+        query: The search query.
+        type: Which search index to query: ``web`` (default), ``news``, or
+            ``images``. Omitted from the request when ``None`` so the server
+            applies its own default.
+        limit: Max number of organic results (1-100, default 10 server-side).
+        country: Two-letter country code to localize results (e.g. ``us``).
+        language: Two-letter ISO-639-1 language code (e.g. ``en``).
+        date_range: Restrict results to a recency window: ``any`` (default),
+            ``hour``, ``day``, ``week``, ``month``, or ``year``. Omitted from
+            the request when ``None``.
+
+    Returns:
+        The parsed 200 response model.
+
+    Raises:
+        errors.UnexpectedStatus: On any non-200 response. ``.status_code`` and
+            ``.content`` are always populated; ``.code``/``.message`` are populated
+            when the body is the documented ``Error`` envelope.
+    """
+    # Imported lazily: the generated operation imports this module, so a
+    # top-level import would create a circular dependency.
+    from .api.search import create_search
+    from .models.create_search_body import CreateSearchBody
+    from .models.create_search_body_date_range import CreateSearchBodyDateRange
+    from .models.create_search_body_type import CreateSearchBodyType
+    from .models.create_search_response_200 import CreateSearchResponse200
+    from .types import UNSET
+
+    # Pass UNSET (not the model's default) for absent type/date_range so the
+    # wire body stays minimal and an omitted filter is truly omitted, matching
+    # the optional-field contract across the SDKs.
+    body = CreateSearchBody(
+        query=query,
+        type_=CreateSearchBodyType(type) if type is not None else UNSET,
+        limit=limit if limit is not None else UNSET,
+        country=country if country is not None else UNSET,
+        language=language if language is not None else UNSET,
+        date_range=(CreateSearchBodyDateRange(date_range) if date_range is not None else UNSET),
+    )
+
+    # Own request -> parse directly rather than delegating to sync_detailed, whose
+    # generated _parse_response calls response.json() unconditionally on documented
+    # statuses and would raise json.JSONDecodeError inside the SDK on an HTML error
+    # page before the wrapper could inspect the response.
+    kwargs = create_search._get_kwargs(body=body)
+    response = self.get_httpx_client().request(**kwargs)
+    if response.status_code == 200:
+        return CreateSearchResponse200.from_dict(response.json())
+    raise _search_unexpected(response)
+
+
+AuthenticatedClient.search = _search

bytekit/errors.py

@@ -0,0 +1,18 @@
+"""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, *, code=None, message=None):  # BYTEKIT-ERR-ENRICH
+        self.status_code = status_code
+        self.content = content
+        self.code = code
+        self.message = message
+
+        super().__init__(
+            f"Unexpected status code: {status_code}\n\nResponse content:\n{content.decode(errors='ignore')}"
+        )
+
+
+__all__ = ["UnexpectedStatus"]