nadeshiko-sdk 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

nadeshiko/__init__.py

@@ -1,10 +1,9 @@
 """A client library for accessing Nadeshiko API"""
 
 from ._version import __version__
-from .client import Environment, Nadeshiko
+from .client import AuthenticatedClient as Nadeshiko
 
 __all__ = (
     "Nadeshiko",
-    "Environment",
     "__version__",
 )

nadeshiko/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.2.0"

nadeshiko/client.py

@@ -1,103 +1,226 @@
 import ssl
-from enum import Enum
 from typing import Any
 
 import httpx
 from attrs import define, evolve, field
 
 
-class Environment(Enum):
-    """API environment presets."""
+@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})
 
-    LOCAL = "http://localhost:5000"
-    PRODUCTION = "https://api.nadeshiko.co"
+    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 _resolve_base_url(base_url: str | Environment) -> str:
-    """Resolve environment enum to URL, or return URL string as-is."""
-    if isinstance(base_url, Environment):
-        return base_url.value
-    return base_url
+    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 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) -> "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 Nadeshiko:
-    """Nadeshiko API client.
-
-    Example:
-        >>> from nadeshiko import Nadeshiko, Environment
-        >>> from nadeshiko.api.search import search
-        >>>
-        >>> client = Nadeshiko(api_key="your-key")
-        >>> result = search.sync(client=client, body={"query": "..."})
-
-    Args:
-        api_key: Your Nadeshiko API key
-        base_url: API environment (Environment.PRODUCTION, Environment.LOCAL) or custom URL string
-        timeout: Request timeout
-        verify_ssl: Whether to verify SSL certificates
-        follow_redirects: Whether to follow redirects
-        raise_on_unexpected_status: Whether to raise on unexpected status codes
-        httpx_args: Additional arguments for httpx.Client
+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
     """
 
-    _api_key: str = field(alias="api_key")
-    _base_url: str | Environment = field(default=Environment.PRODUCTION, alias="base_url")
+    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")
-    _raise_on_unexpected_status: bool = field(
-        default=False, kw_only=True, alias="raise_on_unexpected_status"
-    )
     _client: httpx.Client | None = field(default=None, init=False)
     _async_client: httpx.AsyncClient | None = field(default=None, init=False)
 
-    @property
-    def raise_on_unexpected_status(self) -> bool:
-        """Whether to raise on unexpected status codes."""
-        return self._raise_on_unexpected_status
+    token: str
+    prefix: str = "Bearer"
+    auth_header_name: str = "Authorization"
 
-    def with_headers(self, headers: dict[str, str]) -> "Nadeshiko":
-        """Get a new client matching this one with additional headers."""
+    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]) -> "Nadeshiko":
-        """Get a new client matching this one with additional cookies."""
+    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) -> "Nadeshiko":
-        """Get a new client matching this one with a new timeout configuration."""
+    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)
 
-    # Internal methods required by generated API functions
-    # These are not part of the public API
+    def set_httpx_client(self, client: httpx.Client) -> "AuthenticatedClient":
+        """Manually set the underlying httpx.Client
 
-    def set_httpx_client(self, client: httpx.Client) -> "Nadeshiko":
+        **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:
-            headers = {**self._headers, "X-API-Key": self._api_key}
+            self._headers[self.auth_header_name] = (
+                f"{self.prefix} {self.token}" if self.prefix else self.token
+            )
             self._client = httpx.Client(
-                base_url=_resolve_base_url(self._base_url),
+                base_url=self._base_url,
                 cookies=self._cookies,
-                headers=headers,
+                headers=self._headers,
                 timeout=self._timeout,
                 verify=self._verify_ssl,
                 follow_redirects=self._follow_redirects,
@@ -105,24 +228,33 @@ class Nadeshiko:
             )
         return self._client
 
-    def __enter__(self) -> "Nadeshiko":
+    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) -> "Nadeshiko":
+    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> "AuthenticatedClient":
+        """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:
-            headers = {**self._headers, "X-API-Key": self._api_key}
+            self._headers[self.auth_header_name] = (
+                f"{self.prefix} {self.token}" if self.prefix else self.token
+            )
             self._async_client = httpx.AsyncClient(
-                base_url=_resolve_base_url(self._base_url),
+                base_url=self._base_url,
                 cookies=self._cookies,
-                headers=headers,
+                headers=self._headers,
                 timeout=self._timeout,
                 verify=self._verify_ssl,
                 follow_redirects=self._follow_redirects,
@@ -130,9 +262,11 @@ class Nadeshiko:
             )
         return self._async_client
 
-    async def __aenter__(self) -> "Nadeshiko":
+    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)

{nadeshiko_sdk-0.1.0.dist-info → nadeshiko_sdk-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nadeshiko-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python SDK for Nadeshiko API
 Requires-Python: >=3.11
 Requires-Dist: attrs>=23.0
@@ -17,6 +17,9 @@ Description-Content-Type: text/markdown
 
 # Nadeshiko Python SDK
 
+[![PyPI](https://img.shields.io/pypi/v/nadeshiko-sdk)](https://pypi.org/project/nadeshiko-sdk/)
+
+
 Python SDK for the [Nadeshiko API](https://nadeshiko.co)
 
 ## Quick Start

{nadeshiko_sdk-0.1.0.dist-info → nadeshiko_sdk-0.2.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-nadeshiko/__init__.py,sha256=jjn5gWMKhcaeM-4U-7o8U612jfmBraHdqYzRqMDUvEE,199
-nadeshiko/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
-nadeshiko/client.py,sha256=23sewMBgxMhjbI1-pob_dMqO5ZzP1fl_dkGCEaZSi48,5459
+nadeshiko/__init__.py,sha256=aeAjSMM5BYro2XyF18xzV3c0AlWyPLxr2iJijsB7Tks,190
+nadeshiko/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+nadeshiko/client.py,sha256=KI0gSZL9TUd9vfpb6T01eliMBmRbqGv_-Gbmp-E--pg,12448
 nadeshiko/errors.py,sha256=gO8GBmKqmSNgAg-E5oT-oOyxztvp7V_6XG7OUTT15q0,546
 nadeshiko/types.py,sha256=0We4NPvhIYASRpQ3le41nmJeEAVm42-2VKdzlJ4Ogok,1343
 nadeshiko/api/__init__.py,sha256=zTSiG_ujSjAqWPyc435YXaX9XTlpMjiJWBbV-f-YtdA,45
@@ -162,6 +162,6 @@ nadeshiko/models/user_info_response_user.py,sha256=JTCD9BMIcH1ygWcyB8VfYZjcQwi-w
 nadeshiko/models/user_role.py,sha256=je_tlp39e-2jlzwBnmjkr6ymhJ6olWKTPEtFExEsHGE,1811
 nadeshiko/models/word_match.py,sha256=Yaf5_bSK4Dk93EHqOesb9jQ8BlQlX4NUU39GpupEl7A,3285
 nadeshiko/models/word_match_media.py,sha256=6eKrsm3fQHe2mLYNQ4aRQCU7JrMaIoJqw7NTA2o_2-Y,3094
-nadeshiko_sdk-0.1.0.dist-info/METADATA,sha256=ZdEJglmBYua2njxdOHzba94kEjSy91l1_p-sVXysW4g,3946
-nadeshiko_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-nadeshiko_sdk-0.1.0.dist-info/RECORD,,
+nadeshiko_sdk-0.2.0.dist-info/METADATA,sha256=gq-rQIr6hh7L4XVDlx1JYweeTCmPNOx5MjOleQUzcl0,4044
+nadeshiko_sdk-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nadeshiko_sdk-0.2.0.dist-info/RECORD,,