clientcraft 0.1.0__py3-none-any.whl

clientcraft/__init__.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+
+# Base utilities (useful for custom backends or extensions)
+from ._base import HttpError, PreparedRequest, prepare_request
+
+# Endpoint types (sync)
+# Endpoint types (async) - same runtime behavior, different type stubs
+# Extraction utility
+from ._endpoints import (
+    AsyncDelete,
+    AsyncGet,
+    AsyncPatch,
+    AsyncPost,
+    AsyncPut,
+    Delete,
+    Get,
+    Patch,
+    Post,
+    Put,
+    extract_endpoint_info,
+)
+
+# Response wrappers
+from ._responses import BytesResponse, TextResponse
+
+# Core types
+from ._types import EndpointInfo, ExtractedEndpoint, RequestStyle, ResponseStyle
+
+# Clients
+from .async_client import AsyncAPIClient
+
+# Backend protocols (for type annotations)
+from .backends import AsyncHttpBackend, HttpBackend, HttpResponse
+from .client import APIClient
+
+__version__ = version("clientcraft")
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core types
+    "EndpointInfo",
+    "ExtractedEndpoint",
+    "RequestStyle",
+    "ResponseStyle",
+    # Response wrappers
+    "BytesResponse",
+    "TextResponse",
+    # Sync endpoint types
+    "Delete",
+    "Get",
+    "Patch",
+    "Post",
+    "Put",
+    # Async endpoint types
+    "AsyncDelete",
+    "AsyncGet",
+    "AsyncPatch",
+    "AsyncPost",
+    "AsyncPut",
+    # Utilities
+    "extract_endpoint_info",
+    "prepare_request",
+    # Errors
+    "HttpError",
+    "PreparedRequest",
+    # Clients
+    "APIClient",
+    "AsyncAPIClient",
+    # Backend protocols
+    "HttpBackend",
+    "AsyncHttpBackend",
+    "HttpResponse",
+]

clientcraft/__init__.pyi

@@ -0,0 +1,47 @@
+from collections.abc import Coroutine
+from typing import Any
+
+from pydantic import BaseModel
+
+from ._base import HttpError as HttpError
+from ._base import PreparedRequest as PreparedRequest
+from ._base import prepare_request as prepare_request
+from ._responses import BytesResponse as BytesResponse
+from ._responses import TextResponse as TextResponse
+from ._types import EndpointInfo as EndpointInfo
+from ._types import ExtractedEndpoint as ExtractedEndpoint
+from ._types import RequestStyle as RequestStyle
+from ._types import ResponseStyle as ResponseStyle
+from .async_client import AsyncAPIClient as AsyncAPIClient
+from .backends import AsyncHttpBackend as AsyncHttpBackend
+from .backends import HttpBackend as HttpBackend
+from .backends import HttpResponse as HttpResponse
+from .client import APIClient as APIClient
+
+# Metaclass exposing runtime subscription: at runtime ``Get[Req, Resp, Path]`` is
+# evaluated by ``_EndpointTypeMeta.__getitem__`` and returns an ``Annotated`` type.
+# Declaring it on the base classes (subclasses inherit it) lets a value of type
+# ``type[Get]`` be used as a subscriptable factory (e.g. in tests) without losing
+# static typing on the generic-class annotation form.
+class _EndpointTypeMeta(type):
+    def __getitem__(cls, params: tuple[type, type | None, object]) -> object: ...
+
+class Endpoint[TRequest: BaseModel, TResponse: BaseModel | None](metaclass=_EndpointTypeMeta):
+    def __call__(self, request: TRequest) -> TResponse: ...
+
+class Get[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](Endpoint[TRequest, TResponse]): ...
+class Post[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](Endpoint[TRequest, TResponse]): ...
+class Put[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](Endpoint[TRequest, TResponse]): ...
+class Patch[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](Endpoint[TRequest, TResponse]): ...
+class Delete[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](Endpoint[TRequest, TResponse]): ...
+
+class AsyncEndpoint[TRequest: BaseModel, TResponse: BaseModel | None](metaclass=_EndpointTypeMeta):
+    def __call__(self, request: TRequest) -> Coroutine[Any, Any, TResponse]: ...
+
+class AsyncGet[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](AsyncEndpoint[TRequest, TResponse]): ...
+class AsyncPost[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](AsyncEndpoint[TRequest, TResponse]): ...
+class AsyncPut[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](AsyncEndpoint[TRequest, TResponse]): ...
+class AsyncPatch[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](AsyncEndpoint[TRequest, TResponse]): ...
+class AsyncDelete[TRequest: BaseModel, TResponse: BaseModel | None, TPath: str](AsyncEndpoint[TRequest, TResponse]): ...
+
+def extract_endpoint_info(hint: object) -> ExtractedEndpoint | None: ...

clientcraft/_base.py

@@ -0,0 +1,300 @@
+"""
+Shared utilities for sync and async API clients.
+
+This module contains the common infrastructure that both sync and async clients share:
+- Request/response handling utilities
+- Generic base client class with __init_subclass__ processing
+- Generic endpoint descriptor parameterized by bound endpoint type
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, get_type_hints
+from urllib.parse import urlencode
+
+from pydantic import BaseModel
+
+from ._endpoints import extract_endpoint_info
+from ._responses import BytesResponse, TextResponse
+from ._types import EndpointInfo, RequestStyle, ResponseStyle
+from .backends import HttpResponse
+
+# ---------------------------------------------------------------------------
+# HTTP Error
+# ---------------------------------------------------------------------------
+
+
+class HttpError(Exception):
+    """HTTP error with status code and response content."""
+
+    def __init__(self, status_code: int, content: bytes, headers: dict[str, str] | None = None) -> None:
+        self.status_code = status_code
+        self.content = content
+        self.headers = headers or {}
+        super().__init__(f"HTTP {status_code}: {content.decode('utf-8', errors='replace')}")
+
+
+# ---------------------------------------------------------------------------
+# Request Preparation
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    """
+    A fully prepared HTTP request ready to be sent.
+
+    Separating preparation from execution enables:
+    - Easy testing (inspect the request before sending)
+    - Middleware/interceptors
+    - Retries with the same prepared request
+    """
+
+    method: str
+    url: str
+    content: bytes | None
+    headers: dict[str, str]
+
+
+def extract_path_params(path_template: str) -> set[str]:
+    """Extract parameter names from a path template like '/users/{user_id}'."""
+    return set(re.findall(r"\{(\w+)\}", path_template))
+
+
+def serialize_query_value(value: object) -> str:
+    """Serialize a value for use in query string."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, list):
+        return ",".join(str(item) for item in value)
+    return str(value)
+
+
+def prepare_request(
+    request: BaseModel,
+    endpoint_info: EndpointInfo,
+    path_params: set[str],
+    base_url: str,
+    default_headers: dict[str, str],
+) -> PreparedRequest:
+    """Build a PreparedRequest from the endpoint info and request data."""
+    request_dict = request.model_dump(exclude_none=True)
+
+    # Build URL with path interpolation
+    url_path = endpoint_info.path
+    for param in path_params:
+        if param not in request_dict:
+            raise ValueError(f"Path parameter '{param}' not found in request")
+        url_path = url_path.replace(f"{{{param}}}", str(request_dict[param]))
+
+    url = f"{base_url.rstrip('/')}/{url_path.lstrip('/')}"
+
+    # Serialize based on request_style (from endpoint metadata, not HTTP method)
+    content: bytes | None = None
+
+    if endpoint_info.request_style == RequestStyle.QUERY:
+        # Add non-path params to query string
+        query_params = {k: serialize_query_value(v) for k, v in request_dict.items() if k not in path_params}
+        if query_params:
+            url = f"{url}?{urlencode(query_params)}"
+
+    elif endpoint_info.request_style == RequestStyle.BODY:
+        # Serialize non-path params to JSON body
+        body_dict = {k: v for k, v in request_dict.items() if k not in path_params}
+        if body_dict:
+            content = json.dumps(body_dict).encode("utf-8")
+
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        **default_headers,
+    }
+
+    return PreparedRequest(
+        method=endpoint_info.method.name,
+        url=url,
+        content=content,
+        headers=headers,
+    )
+
+
+def parse_response(
+    response: HttpResponse,
+    endpoint_info: EndpointInfo,
+    response_type: type[BaseModel] | None,
+) -> BaseModel | dict[str, Any] | list[Any] | None:
+    """Parse response based on response_style."""
+    style = endpoint_info.response_style
+
+    if style == ResponseStyle.NONE:
+        # No body expected - return None
+        return None
+
+    if style == ResponseStyle.TEXT:
+        # Return text content
+        return TextResponse(content=response.content.decode("utf-8"))
+
+    if style == ResponseStyle.BYTES:
+        # Return raw bytes
+        return BytesResponse(content=response.content)
+
+    # Default: JSON
+    if response_type is not None:
+        # Handle empty body gracefully for JSON
+        if not response.content or response.content.strip() == b"":
+            # If response type has no required fields, return empty instance
+            # Otherwise this will raise a validation error (which is correct)
+            return response_type.model_validate({})
+        return response_type.model_validate_json(response.content)
+
+    # No response type specified - return raw dict/list
+    if not response.content or response.content.strip() == b"":
+        return None
+    result: dict[str, Any] | list[Any] = json.loads(response.content)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Generic Base Client
+# ---------------------------------------------------------------------------
+
+
+class BaseAPIClient[Backend]:
+    """
+    Generic base class for declarative API clients.
+
+    This handles all the shared logic for both sync and async clients:
+    - __init_subclass__ processing of type hints
+    - __init__ with base_url, backend, headers, timeout
+
+    The Backend type parameter allows subclasses to specify their backend type.
+    Concrete subclasses must define `_descriptor_factory` to create the appropriate
+    descriptor type (sync or async).
+    """
+
+    # Subclasses must set this to their descriptor factory
+    _descriptor_factory: type[EndpointDescriptor[Any]]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Process Annotated type hints and create endpoint descriptors."""
+        super().__init_subclass__(**kwargs)
+
+        # Skip processing if this is still an abstract base
+        if not hasattr(cls, "_descriptor_factory"):
+            return
+
+        try:
+            hints = get_type_hints(cls, include_extras=True)
+        except Exception:
+            hints = {}
+
+        for name, hint in hints.items():
+            extracted = extract_endpoint_info(hint)
+
+            if extracted is not None:
+                descriptor = cls._descriptor_factory(
+                    endpoint_info=extracted.info,
+                    request_type=extracted.request_type,
+                    response_type=extracted.response_type,
+                )
+                setattr(cls, name, descriptor)
+
+    def __init__(
+        self,
+        base_url: str,
+        backend: Backend,
+        *,
+        default_headers: dict[str, str] | None = None,
+        default_timeout: float | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._backend = backend
+        self._default_headers = default_headers or {}
+        self._default_timeout = default_timeout
+
+
+# ---------------------------------------------------------------------------
+# Generic Endpoint Descriptor
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EndpointDescriptor[ClientT: BaseAPIClient[Any]]:
+    """
+    Generic descriptor that creates bound endpoint callables.
+
+    Subclasses override `_create_bound_endpoint` to return the appropriate
+    sync or async bound endpoint type.
+    """
+
+    endpoint_info: EndpointInfo
+    request_type: type[BaseModel] | None
+    response_type: type[BaseModel] | None
+    path_params: set[str] = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.path_params = extract_path_params(self.endpoint_info.path)
+
+    def __get__(self, obj: ClientT | None, objtype: type) -> Any:
+        if obj is None:
+            return self
+        return self._create_bound_endpoint(obj)
+
+    def _create_bound_endpoint(self, client: ClientT) -> Any:
+        """Create a bound endpoint for the given client. Override in subclasses."""
+        raise NotImplementedError("Subclasses must implement _create_bound_endpoint")
+
+
+# ---------------------------------------------------------------------------
+# Base Bound Endpoint
+# ---------------------------------------------------------------------------
+
+# from abc import ABC, abstractmethod
+
+
+# class ParseStrategy[T](ABC):
+#     def __init__(self, response_type: type[T]) -> None:
+#         self.response_type: type[T] = response_type
+
+#     @abstractmethod
+#     def parse(self, response: HttpResponse) -> T:
+#         raise NotImplementedError
+
+# class ParsePydanticModel[T: BaseModel](ParseStrategy[T]):
+#     def parse(self, response: HttpResponse) -> T:
+#         data = response.content
+#         return self.response_type.model_validate(data)
+
+
+@dataclass
+class BaseBoundEndpoint[ClientT: BaseAPIClient[Any]]:
+    """
+    Base class for bound endpoints with shared preparation logic.
+
+    Subclasses implement __call__ (sync) or __call__ as async.
+    """
+
+    client: ClientT
+    endpoint_info: EndpointInfo
+    response_type: type[BaseModel] | None
+    path_params: set[str]
+    # parse_strategy: ParseStrategy
+
+    def _prepare(self, request: BaseModel) -> PreparedRequest:
+        """Build a PreparedRequest from the endpoint info and request data."""
+        return prepare_request(
+            request=request,
+            endpoint_info=self.endpoint_info,
+            path_params=self.path_params,
+            base_url=self.client._base_url,
+            default_headers=self.client._default_headers,
+        )
+
+    def _handle_response(self, response: HttpResponse) -> BaseModel | dict[str, Any] | list[Any] | None:
+        """Handle response: raise on error, parse on success."""
+        if response.status_code >= 400:
+            raise HttpError(response.status_code, response.content, dict(response.headers))
+        return parse_response(response, self.endpoint_info, self.response_type)

clientcraft/_endpoints.py

@@ -0,0 +1,194 @@
+"""
+Endpoint type construction.
+
+This module defines the endpoint types (Get, Post, Put, Patch, Delete) and their
+async variants (AsyncGet, AsyncPost, etc.) using a metaclass to transform
+`Get[Request, Response, Literal["/path"]]` into an Annotated type with EndpointInfo.
+
+The type stubs (.pyi files) tell type checkers what the return types are:
+- Sync types (Get, Post, etc.) return TResponse directly
+- Async types (AsyncGet, AsyncPost, etc.) return Coroutine[Any, Any, TResponse]
+"""
+
+from __future__ import annotations
+
+from http import HTTPMethod
+from typing import Annotated, Any, Literal, get_args, get_origin
+
+from pydantic import BaseModel
+
+from ._responses import BytesResponse, TextResponse
+from ._types import EndpointInfo, ExtractedEndpoint, RequestStyle, ResponseStyle
+
+
+def _get_response_style(response_type: type | None) -> ResponseStyle:
+    """Determine response style based on response type."""
+    if response_type is None or response_type is type(None):
+        return ResponseStyle.NONE
+    if response_type is TextResponse:
+        return ResponseStyle.TEXT
+    if response_type is BytesResponse:
+        return ResponseStyle.BYTES
+    return ResponseStyle.JSON
+
+
+def _extract_literal(t: Any) -> str | None:
+    """Extract string value from a Literal type."""
+    if get_origin(t) is Literal:
+        args = get_args(t)
+        if args and isinstance(args[0], str):
+            return args[0]
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Marker type for endpoints
+# ---------------------------------------------------------------------------
+
+
+class Endpoint[TRequest: BaseModel, TResponse: BaseModel]:
+    """
+    Marker type for endpoints.
+
+    This class is never instantiated - it only exists to carry type parameters.
+    The actual callable behavior comes from the descriptor created by APIClient.
+    """
+
+    def __call__(self, request: TRequest) -> TResponse:
+        """Type signature for the endpoint call."""
+        raise NotImplementedError("Endpoint should be used via APIClient")
+
+
+# ---------------------------------------------------------------------------
+# Metaclass for endpoint type construction
+# ---------------------------------------------------------------------------
+
+
+class _EndpointTypeMeta(type):
+    """Metaclass that makes Get[Req, Resp, Literal["/path"]] return an Annotated type."""
+
+    _method: HTTPMethod
+    _request_style: RequestStyle
+
+    def __getitem__(cls, params: tuple[type, type, Any]) -> Any:
+        if not isinstance(params, tuple) or len(params) != 3:
+            raise TypeError(f"{cls.__name__} requires 3 type parameters: [Request, Response, Path]")
+
+        request_type, response_type, path_type = params
+
+        # Extract path from Literal
+        path = _extract_literal(path_type)
+        if path is None and isinstance(path_type, str):
+            path = path_type
+
+        if path is None:
+            raise TypeError(f"Path must be a Literal string, got {path_type}")
+
+        # Determine response style from response type
+        response_style = _get_response_style(response_type)
+
+        # Return Annotated type with endpoint info
+        # Type checkers can't understand runtime type construction - we use .pyi stubs instead
+        return Annotated[
+            Endpoint[request_type, response_type],  # type: ignore[valid-type]
+            EndpointInfo(
+                method=cls._method,
+                path=path,
+                request_style=cls._request_style,
+                response_style=response_style,
+            ),
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Sync endpoint types
+# ---------------------------------------------------------------------------
+
+
+class Get(metaclass=_EndpointTypeMeta):
+    """GET endpoint type - sends data as query parameters."""
+
+    _method = HTTPMethod.GET
+    _request_style = RequestStyle.QUERY
+
+
+class Post(metaclass=_EndpointTypeMeta):
+    """POST endpoint type - sends data as JSON body."""
+
+    _method = HTTPMethod.POST
+    _request_style = RequestStyle.BODY
+
+
+class Put(metaclass=_EndpointTypeMeta):
+    """PUT endpoint type - sends data as JSON body."""
+
+    _method = HTTPMethod.PUT
+    _request_style = RequestStyle.BODY
+
+
+class Patch(metaclass=_EndpointTypeMeta):
+    """PATCH endpoint type - sends data as JSON body."""
+
+    _method = HTTPMethod.PATCH
+    _request_style = RequestStyle.BODY
+
+
+class Delete(metaclass=_EndpointTypeMeta):
+    """DELETE endpoint type - sends data as query parameters."""
+
+    _method = HTTPMethod.DELETE
+    _request_style = RequestStyle.QUERY
+
+
+# ---------------------------------------------------------------------------
+# Async endpoint types
+#
+# At runtime, these behave identically to the sync versions.
+# The type stubs (.pyi) tell type checkers that these return Coroutine.
+# ---------------------------------------------------------------------------
+
+AsyncGet = Get
+AsyncPost = Post
+AsyncPut = Put
+AsyncPatch = Patch
+AsyncDelete = Delete
+
+
+# ---------------------------------------------------------------------------
+# Extraction utility
+# ---------------------------------------------------------------------------
+
+
+def extract_endpoint_info(hint: Any) -> ExtractedEndpoint | None:
+    """
+    Extract endpoint info from an Annotated type hint.
+
+    Returns ExtractedEndpoint if the hint is a valid endpoint type, None otherwise.
+    """
+    if get_origin(hint) is not Annotated:
+        return None
+
+    args = get_args(hint)
+    if len(args) < 2:
+        return None
+
+    base_type, *annotations = args
+    base_args = get_args(base_type)
+
+    if len(base_args) < 2:
+        return None
+
+    request_type, response_type = base_args[0], base_args[1]
+
+    if not isinstance(request_type, type) or not isinstance(response_type, type):
+        return None
+
+    endpoint_info = next((a for a in annotations if isinstance(a, EndpointInfo)), None)
+    if endpoint_info is None:
+        return None
+
+    return ExtractedEndpoint(
+        request_type=request_type,
+        response_type=response_type,
+        info=endpoint_info,
+    )

clientcraft/_responses.py

@@ -0,0 +1,32 @@
+"""
+Response wrapper types for non-JSON responses.
+
+These Pydantic models wrap text and binary responses,
+allowing the declarative API to handle all response types uniformly.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class TextResponse(BaseModel):
+    """
+    Wrapper for text responses.
+
+    Usage:
+        get_health: Get[EmptyRequest, TextResponse, Literal["/health"]]
+    """
+
+    content: str
+
+
+class BytesResponse(BaseModel):
+    """
+    Wrapper for binary responses.
+
+    Usage:
+        download_file: Get[FileRequest, BytesResponse, Literal["/files/{id}"]]
+    """
+
+    content: bytes

clientcraft/_types.py

@@ -0,0 +1,54 @@
+"""
+Core types for endpoint definitions.
+
+This module contains the fundamental types used to describe endpoints:
+- RequestStyle: How to serialize request data
+- ResponseStyle: How to deserialize response data
+- EndpointInfo: Metadata bundle stored in Annotated types
+- ExtractedEndpoint: Result of extracting endpoint info from a type hint
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from http import HTTPMethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+class RequestStyle(Enum):
+    """How to serialize request data for the HTTP call."""
+
+    QUERY = auto()  # Serialize to query string (GET, DELETE)
+    BODY = auto()  # Serialize to JSON body (POST, PUT, PATCH)
+
+
+class ResponseStyle(Enum):
+    """How to deserialize response data."""
+
+    JSON = auto()  # Parse as JSON into Pydantic model (default)
+    TEXT = auto()  # Return as string
+    BYTES = auto()  # Return raw bytes
+    NONE = auto()  # No response body expected (204 No Content, etc.)
+
+
+@dataclass(frozen=True)
+class EndpointInfo:
+    """Metadata about an endpoint, stored in Annotated type."""
+
+    method: HTTPMethod
+    path: str
+    request_style: RequestStyle
+    response_style: ResponseStyle
+
+
+@dataclass(frozen=True)
+class ExtractedEndpoint:
+    """Result of extracting endpoint info from a type hint."""
+
+    request_type: type[BaseModel]
+    response_type: type[BaseModel] | None
+    info: EndpointInfo