xAPI-client 1.0.11__py3-none-any.whl

xapi/__init__.py

@@ -0,0 +1,63 @@
+from .apiKey import APIKey
+from .client import Client
+from .endpoint import Endpoint
+from .path import Path, Parameters
+from .rateLimit import RateLimiter
+from .resource import Resource
+from .retry import RetryConfig
+from .type import NotGiven, NotGivenOr, NOTGIVEN
+from .options import Options, IntOptions
+from .model import ResponseModel, ResponseModelList, ResponseModels
+from .query import Query
+from .logger import logger
+from .exceptions import (
+    APIError,
+    APIStatusError,
+    APIResponseValidationError,
+    APIConnectionError,
+    APITimeoutError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    UnprocessableEntityError,
+    RateLimitError,
+    InternalServerError,
+)
+
+logger.configure()
+
+__all__ = [
+    "Client",
+    "Resource",
+    "Endpoint",
+    "APIKey",
+    "RetryConfig",
+    "RateLimiter",
+    "Path",
+    "Parameters",
+    "NotGiven",
+    "NotGivenOr",
+    "NOTGIVEN",
+    "Options",
+    "IntOptions",
+    "ResponseModel",
+    "ResponseModelList",
+    "ResponseModels",
+    "Query",
+    "logger",
+    "APIError",
+    "APIStatusError",
+    "APIResponseValidationError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+]

xapi/apiKey.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+from typing import Literal
+from dataclasses import dataclass
+from .query import Query
+from .type import Headers
+from httpx import Headers as httpxHeaders
+
+
+@dataclass
+class APIKey:
+  """API key authentication configuration.
+
+  Controls how and when authentication is applied to requests.
+
+  **Scope** determines which endpoints require authentication:
+    - ``"All"``: Every request includes the API key automatically.
+    - ``"Endpoint"``: Only endpoints with ``requireAuth=True`` on their
+      parent resource include the API key.
+    - ``"Disabled"``: No authentication is applied.
+
+  **Scheme** determines where the API key is sent:
+    - ``"Header"``: Included as an HTTP header on every matching request.
+    - ``"Query"``: Appended as a query parameter on matching requests.
+
+  Args:
+    key: The header or query parameter name (e.g. ``"x-api-key"``).
+    secret: The API key value.
+    scope: Authentication scope (``"All"``, ``"Endpoint"``, or ``"Disabled"``).
+    scheme: Delivery method (``"Header"`` or ``"Query"``).
+
+  Usage::
+
+    apiKey = APIKey(key="x-api-key", secret="sk-...", scope="All", scheme="Header")
+    client = Client(url="https://api.example.com", apiKey=apiKey)
+  """
+
+  key: str
+  secret: str
+  scope: Literal["All", "Endpoint", "Disabled"]
+  scheme: Literal["Header", "Query"]
+
+  @property
+  def authenticate(self) -> dict[str, str]:
+    return {self.key: self.secret}
+
+  @property
+  def header(self) -> Headers:
+    return {self.key: self.secret}
+
+  @property
+  def query(self) -> Query:
+    return Query({self.key: self.secret})
+
+  @property
+  def util(self) -> APIKeyUtil:
+    return APIKeyUtil(self)
+
+class APIKeyUtil:
+  """Internal helper that injects API key credentials into headers or query params.
+
+  Used by the Client during request building to apply authentication based
+  on the APIKey's scope and scheme configuration.
+  """
+  _apiKey: APIKey
+  def __init__(self, apiKey: APIKey):
+    self._apiKey = apiKey
+
+  def allInHeader(self, header: httpxHeaders):
+    """Inject API key into headers if scope is ``"All"``."""
+    if self._apiKey.scope == "All":
+      header.update(self._apiKey.header)
+    return header
+
+  def allInQuery(self, query: Query):
+    """Inject API key into query params if scope is ``"All"``."""
+    if self._apiKey.scope == "All":
+      return query.addPair(self._apiKey.key, self._apiKey.secret)
+    return query
+
+  def endpointInHeader(self, header: httpxHeaders, auth: bool):
+    """Inject API key into headers if scope is ``"Endpoint"`` and auth is required."""
+    if self._apiKey.scope == "Endpoint" and auth:
+      return header.update(self._apiKey.header)
+    return header
+
+  def endpointInQuery(self, query: Query, auth: bool):
+    """Inject API key into query params if scope is ``"Endpoint"`` and auth is required."""
+    if self._apiKey.scope == "Endpoint" and auth:
+      return query.addPair(self._apiKey.key, self._apiKey.secret)
+    return query

xapi/client.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Type, Optional, get_origin
+
+import httpx
+from pydantic import TypeAdapter
+from .apiKey import APIKey
+from .exceptions import (APIConnectionError, APIResponseValidationError,
+                         APIStatusError, APITimeoutError)
+from .resource import Resource
+from .model import ResponseModels
+from .endpoint import PP
+from .retry import RetryConfig
+from .query import Query
+from .type import DEFAULT_TIMEOUT, JSON, HTTPMethod
+from .url import URL
+from .util import DataManager, Headersx
+from .rateLimit import RateLimiter
+from .logger import logger
+
+
+class Client:
+  """Async, resource-oriented API client for interacting with RESTful APIs.
+
+  Organizes endpoints into a tree of Resources, accessed via dot notation
+  (e.g. ``client.coins.coin(...)``). Handles authentication, rate limiting,
+  retries, and response parsing automatically.
+
+  Args:
+    url: Base URL of the API (e.g. ``"https://api.example.com/v1/"``).
+    apiKey: Optional API key configuration for authentication.
+    timeout: Request timeout. Defaults to 30s overall, 5s connect.
+    rateLimit: Optional sliding-window rate limiter.
+    retry: Retry configuration with exponential backoff. Defaults to 3 attempts.
+    headers: Additional headers merged into every request.
+    debug: Enable debug logging for requests, bindings, and responses.
+
+  Usage::
+
+    async with Client(url="https://api.example.com/v1/") as client:
+        client.add(coinsResource)
+        coin = await client.coins.coin(parameters=CoinParams.Bitcoin)
+  """
+  _logger = logger.debug
+
+  
+  def __init__(self,
+               url: str,
+               apiKey: APIKey | None = None,
+               timeout: httpx.Timeout = DEFAULT_TIMEOUT,
+               rateLimit: RateLimiter | None = None,
+               retry: RetryConfig | None = None,
+               headers: httpx.Headers | None = None,
+               debug: bool = False):
+    self.debug: bool = debug
+    logger.configure() if self.debug else None
+    self.url = URL.normalizeBaseURL(url)
+    self.apiKey = apiKey
+    self.retry = retry or RetryConfig()
+    self.timeout = timeout
+    self.rateLimit = rateLimit
+    self.headers: httpx.Headers = httpx.Headers({**Headersx.default()})
+    self.headers.update(headers) if headers else {}
+    
+    self.apiKey.util.allInHeader(self.headers) if self.apiKey else None
+        
+    self.client = httpx.AsyncClient(
+        base_url=self.url,
+        timeout=self.timeout,
+        headers=self.headers
+        # event_hooks=HttpEventHooks.EventHooks()
+    )
+    self.unsetNestedData: bool = True
+    self._resources: Dict[str, Resource] = {}
+
+
+  def add(self, resource: Resource | list[Resource]) -> None:
+    """Register one or more resources with this client.
+
+    Each resource is bound to the client and becomes accessible as an
+    attribute (e.g. ``client.coins``). Raises ``ValueError`` if a
+    resource with the same name is already registered.
+
+    Args:
+      resource: A single Resource or a list of Resources to register.
+    """
+    _resources = resource if isinstance(resource, list) else [resource]
+
+    for r in _resources:
+      if r.name in self._resources:
+        raise ValueError(f"Resource {r.name} already exists")
+      r._bind(self)
+      self._resources[r.name] = r
+      setattr(self, r.name, r)
+      self._logger(f"[Client +] Resource->{r.name}") if self.debug else None
+
+  def __getattr__(self, item: str) -> Any:
+    resources = self.__dict__.get("_resources")
+    if resources is None:
+      raise AttributeError(item)
+    if item in resources:
+      return resources[item]
+    raise AttributeError(item)
+
+  async def _sendRequest(self,
+                         url: str,
+                         path: str,
+                         pathPrefix: str,
+                         response: Optional[Type[ResponseModels]] = None,
+                         query: Query | None = None,
+                         method: HTTPMethod | str = 'GET',
+                         auth: bool = False,
+                         strictValidation: bool = False) -> ResponseModels | JSON:
+    """Send an HTTP request and parse the response.
+
+    Handles the full request lifecycle: authentication injection, rate limiting,
+    request building, response parsing, and retry logic.
+
+    List vs dict responses are auto-detected from the ``response`` type using
+    ``get_origin()``. If ``response`` is ``list[Model]``, the raw JSON array
+    is validated directly. Otherwise, nested ``data`` keys are unwrapped and
+    API metadata is injected into the parsed ResponseModel.
+
+    Args:
+      url: The full request path (prefix + endpoint path).
+      path: The endpoint-specific path segment.
+      pathPrefix: The resource prefix path.
+      response: The Pydantic model type for response parsing. Pass
+        ``list[Model]`` for array responses, or a single ``ResponseModel``
+        subclass for object responses. ``None`` returns raw JSON.
+      query: Optional query parameters.
+      method: HTTP method (default ``GET``).
+      auth: Whether this request requires authentication.
+      strictValidation: Enable strict Pydantic validation mode.
+
+    Returns:
+      Parsed model instance, list of models, or raw JSON dict.
+
+    Raises:
+      APIStatusError: On 4xx/5xx responses (subclassed by status code).
+      APITimeoutError: When all retry attempts time out.
+      APIConnectionError: When all retry attempts fail to connect.
+      APIResponseValidationError: When response data doesn't match the model.
+    """
+
+    url = URL.normalizePath(url)
+    reqHeaders = self.headers
+    rateLimit = self.rateLimit
+    queries = query if query else Query({})
+
+    
+    if (self.apiKey and self.apiKey.scope == "All") and auth:
+      self.apiKey.util.allInQuery(queries) if self.apiKey.scheme == "Query" else None
+
+    if self.apiKey and self.apiKey.scope == "Endpoint":
+      self.apiKey.util.endpointInQuery(queries, auth) if self.apiKey.scheme == "Query" else None
+
+    queries = queries.toQueryParams()
+    request = self.client.build_request(method, url, params=queries, headers=reqHeaders)
+
+    for attempt in range(self.retry.attempts):
+      try:
+        if rateLimit:
+          await rateLimit.acquire()
+        request = self.client.build_request(
+            method,
+            url,
+            params=queries,
+            headers=reqHeaders,
+        )
+
+        resp = await self.client.send(request)
+
+        apiData = DataManager.buildAPIReponseData(
+            elapsed=resp.elapsed.total_seconds(),
+            method=method,
+            url=self.url + pathPrefix + path,
+            path=path,
+            pathPrefix=pathPrefix,
+            authScope=self.apiKey.scope if self.apiKey else "Disabled",
+            query=query.activeQueries if query else None)
+
+        logger.http(f"{method} /{pathPrefix + path} {resp.elapsed.total_seconds():.2f}s") if self.debug else None
+
+        if resp.status_code >= 400:
+          body = None
+          try:
+            body = resp.json()
+          except Exception:
+            body = resp.text
+
+          message = f"HTTP {resp.status_code}: {resp.reason_phrase} {resp.url} {resp.headers.get_list}"
+          raise APIStatusError.withStatus(message, response=resp, body=body)
+        logger.http(f"{resp}") if self.debug else None
+        rawData = resp.json()
+
+        responseIsList = get_origin(response) is list
+
+        if responseIsList:
+          parsedData = rawData
+        else:
+          parsedData: dict[
+              str,
+              Any] = rawData if not self.unsetNestedData else DataManager.unsetNestData(
+                  rawData)
+
+        if response is None:
+          return parsedData
+
+        try:
+          if responseIsList:
+            adapter = TypeAdapter(response)
+            parsed = adapter.validate_python(parsedData, strict=strictValidation)
+          else:
+            parsedData.update({"api": apiData})
+            adapter = TypeAdapter(response)
+            parsed = adapter.validate_python(parsedData, strict=strictValidation)
+        except Exception as err:
+          raise APIResponseValidationError(
+              response=resp,
+              body=parsedData,
+              message=f"Failed to parse response: {err}") from err
+        return parsed
+
+      except httpx.TimeoutException as err:
+        if attempt == self.retry.attempts - 1:
+          raise APITimeoutError(request=request) from err
+        await self.retry.sleep(attempt)
+
+      except APIStatusError as err:
+        if err.status_code < 500:
+          raise  # 4xx errors — don't retry
+        if attempt == self.retry.attempts - 1:
+          raise
+        await self.retry.sleep(attempt)
+
+      except httpx.ConnectError as err:
+        if attempt == self.retry.attempts - 1:
+          raise APIConnectionError(request=request) from err
+
+        await self.retry.sleep(attempt)
+
+      except Exception:
+        if attempt == self.retry.attempts - 1:
+          raise
+        await self.retry.sleep(attempt)
+
+    raise RuntimeError("Request failed")
+
+  async def _endpointRequest(self,
+                             id: str,
+                             path: str,
+                             prefix: str,
+                             method: HTTPMethod | str,
+                             auth: bool,
+                             parameters: Optional[PP | list[PP]] = None,
+                             query: Query | None = None,
+                             model: Optional[Type[ResponseModels]] = None,
+                             strictValidation: bool = False):
+    """Internal bridge between Resource.prepareRequest and _sendRequest.
+
+    Assembles the full URL from prefix + path and delegates to _sendRequest.
+    """
+    url = prefix + path
+    return await self._sendRequest(url=url,
+                                   path=path,
+                                   pathPrefix=prefix,
+                                   response=model,
+                                   query=query,
+                                   method=method,
+                                   auth=auth,
+                                   strictValidation=strictValidation)
+
+  async def __aenter__(self) -> Client:
+    return self
+
+  async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+    await self.client.aclose()
+
+  async def close(self) -> None:
+    """Close the underlying HTTP connection pool.
+
+    Called automatically when using the client as an async context manager.
+    """
+    self._logger("[Client] Closing client") if self.debug else None
+    await self.client.aclose()

xapi/endpoint.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+from typing import (Protocol, TypeVar, Optional, Type, TYPE_CHECKING)
+from dataclasses import dataclass, field
+from .path import Path, Parameters
+from .type import HTTPMethod
+from .logger import logger
+from .model import ResponseModel, ResponseModels
+from .exceptions import BindingError
+import shortuuid
+if TYPE_CHECKING:
+  from .client import Client
+  from .resource import Resource
+
+logger.configure()
+
+R = TypeVar("R", bound="ResponseModel", covariant=True)
+PP = TypeVar("PP", bound="Parameters",  contravariant=True)
+
+class EndpointCall(Protocol[R, PP]):
+  """Protocol for callable endpoint objects."""
+
+  async def call(self, parameters: Optional[PP | list[PP]] = None, **kwargs):
+    ...
+
+@dataclass
+class Endpoint[R, PP]:
+  """A single API endpoint definition.
+
+  Represents one callable API operation (e.g. ``GET /coins/{id}``). Endpoints
+  are attached to a Resource and become callable via dot notation on the client.
+
+  The ``response`` type determines how the API response is parsed:
+    - ``ResponseModel`` subclass: parsed as a single object, with API metadata
+      injected into the ``api`` field.
+    - ``list[BaseModel]``: parsed as a JSON array of models (auto-detected).
+    - ``None``: returns raw JSON dict without parsing.
+
+  Args:
+    name: Identifier used as the Python attribute name on the resource.
+    path: Path object defining the URL template and parameter requirements.
+    nameOverride: Optional display name for the endpoint (defaults to ``name``).
+    response: Pydantic model type for response parsing. Use ``list[Model]`` for
+      array responses.
+    method: HTTP method. Defaults to ``GET``.
+    strict: Enable strict Pydantic validation mode.
+    debug: Enable debug logging for this endpoint.
+  """
+
+  __id__: str = field(init=False) 
+  __client__: Optional[Client] = field(init=False, default=None)
+  __boundResource__: Optional[Resource] = field(init=False, default=None)
+  __prefix__: str = field(init=False, default="")
+  __apiName__: str = field(init=False, default="")
+  _requireAuth: bool = field(init=False, default=False) 
+  name: str
+  path: Path[PP]
+  nameOverride: str = ""
+  response: Optional[Type[ResponseModels]] = None
+  method: HTTPMethod = "GET"
+  strict: bool = False
+
+  debug: bool = False
+
+  def __post_init__(self):
+    self.__id__ = str(shortuuid.uuid(name=self.name+self.path.endpointPath))
+    self.__apiName__ = self.nameOverride if self.nameOverride != "" else self.name
+
+  def _bind(self, resource: Resource, prefix: str = "") -> None:
+    self.__boundResource__ = resource
+    self.debug = self.__boundResource__.debug
+    self._requireAuth = self.__boundResource__._requireAuth
+    logger.debug(f"[Bind] {resource.name}<-{self.name}") if self.debug else None
+
+  @property
+  def id(self) -> str:
+    return self.__id__
+
+  def _getPath(self, params: Optional[PP | list[PP]] = None) -> str:
+    if params is not None and self.path.requiresParameters:
+      return self.path.path(params=params)
+    return self.path.path()
+
+  async def call(self, parameters: Optional[PP | list[PP]] = None, **kwargs):
+    """Execute this endpoint's API call.
+
+    Resolves the URL path with any provided parameters, then delegates
+    to the bound resource to send the request through the client.
+
+    Args:
+      parameters: Path parameter values to inject into the URL template.
+      **kwargs: Additional options. Pass ``query=Query(...)`` to include
+        query parameters.
+
+    Returns:
+      Parsed response model, list of models, or raw JSON dict.
+
+    Raises:
+      BindingError: If this endpoint hasn't been added to a resource.
+    """
+    if not self.__boundResource__:
+      raise BindingError(self.name, "Resource")
+
+    if self.path.requiresParameters and parameters:
+      path = self._getPath(parameters)
+    else:
+      path = self._getPath()
+
+    if not self.__boundResource__._pathProtection:
+      pFix = self.__boundResource__._prefix
+    else:
+      pFix = self.__boundResource__._prefix 
+
+    queries = kwargs.get("query")
+
+    result = await self.__boundResource__.prepareRequest(
+        id=self.__id__,
+        path=path,
+        prefix=pFix,
+        method=self.method,
+        auth=self._requireAuth,
+        model=self.response,
+        strictValidation=self.strict,
+        query=queries,
+    )
+    return result
+
+
+type Endpoints[R, PP] = Endpoint[R, PP]