unique_toolkit 0.8.43__tar.gz → 0.8.44__tar.gz

{unique_toolkit-0.8.43 → unique_toolkit-0.8.44}/CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.44] - 2025-09-03
+- Refine `EndpointClass` and create `EndpointRequestor`
+
 ## [0.8.43] - 2025-09-03
 - Add alias for `UniqueSettings` api base `API_BASE`
 

{unique_toolkit-0.8.43 → unique_toolkit-0.8.44}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 0.8.43
+Version: 0.8.44
 Summary: 
 License: Proprietary
-Author: Martin Fadler
-Author-email: martin.fadler@unique.ch
+Author: Cedric Klinkert
+Author-email: cedric.klinkert@unique.ch
 Requires-Python: >=3.11,<4.0
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
@@ -117,6 +117,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.44] - 2025-09-03
+- Refine `EndpointClass` and create `EndpointRequestor`
+
 ## [0.8.43] - 2025-09-03
 - Add alias for `UniqueSettings` api base `API_BASE`
 

{unique_toolkit-0.8.43 → unique_toolkit-0.8.44}/pyproject.toml

@@ -1,8 +1,9 @@
 [tool.poetry]
 name = "unique_toolkit"
-version = "0.8.43"
+version = "0.8.44"
 description = ""
 authors = [
+    "Cedric Klinkert <cedric.klinkert@unique.ch>",
     "Martin Fadler <martin.fadler@unique.ch>",
     "Sadique Sheik <sadique@unique.ch>",
     "Fabian Schläpfer <fabian@unique.ch>",

unique_toolkit-0.8.44/unique_toolkit/_common/endpoint_builder.py

@@ -0,0 +1,221 @@
+"""
+This module provides a minimal framework for building endpoint classes such that a client can use
+the endpoints without having to know the details of the endpoints.
+"""
+
+from enum import StrEnum
+from string import Formatter, Template
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    ParamSpec,
+    Protocol,
+    TypeVar,
+)
+
+from pydantic import BaseModel
+
+# Paramspecs
+PayloadParamSpec = ParamSpec("PayloadParamSpec")
+PathParamsSpec = ParamSpec("PathParamsSpec")
+
+# Type variables
+ResponseType = TypeVar("ResponseType", bound=BaseModel, covariant=True)
+PathParamsType = TypeVar("PathParamsType", bound=BaseModel)
+PayloadType = TypeVar("PayloadType", bound=BaseModel)
+
+# Helper type to extract constructor parameters
+
+# Type for the constructor of a Pydantic model
+ModelConstructor = Callable[..., BaseModel]
+
+
+class EndpointMethods(StrEnum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+
+
+# Necessary for typing of make_endpoint_class
+class EndpointClassProtocol(
+    Protocol,
+    Generic[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        ResponseType,
+    ],
+):
+    path_params_model: type[PathParamsType]
+    payload_model: type[PayloadType]
+    response_model: type[ResponseType]
+
+    @staticmethod
+    def create_url(
+        *args: PathParamsSpec.args, **kwargs: PathParamsSpec.kwargs
+    ) -> str: ...
+
+    @staticmethod
+    def create_url_from_model(path_params: PathParamsType) -> str: ...
+
+    @staticmethod
+    def create_payload(
+        *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
+    ) -> dict[str, Any]: ...
+
+    @staticmethod
+    def create_payload_from_model(payload: PayloadType) -> dict[str, Any]: ...
+
+    @staticmethod
+    def handle_response(response: dict[str, Any]) -> ResponseType: ...
+
+    @staticmethod
+    def request_method() -> EndpointMethods: ...
+
+
+# Model for any client to implement
+def build_endpoint_class(
+    *,
+    method: EndpointMethods,
+    url_template: Template,
+    path_params_constructor: Callable[PathParamsSpec, PathParamsType],
+    payload_constructor: Callable[PayloadParamSpec, PayloadType],
+    response_model_type: type[ResponseType],
+    dump_options: dict | None = None,
+) -> type[
+    EndpointClassProtocol[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        ResponseType,
+    ]
+]:
+    """Generate a class with static methods for endpoint handling.
+
+    Uses separate models for path parameters and request body for clean API design.
+
+    Returns a class with static methods:
+    - create_url: Creates URL from path parameters
+    - create_payload: Creates request body payload
+    """
+
+    # Verify that the path_params_constructor and payload_constructor are valid pydantic models
+    if not isinstance(path_params_constructor, type(BaseModel)):
+        raise ValueError("path_params_constructor must be a pydantic model")
+    if not isinstance(payload_constructor, type(BaseModel)):
+        raise ValueError("payload_constructor must be a pydantic model")
+
+    if not dump_options:
+        dump_options = {
+            "exclude_unset": True,
+            "by_alias": True,
+            "exclude_defaults": True,
+        }
+
+    class EndpointClass(EndpointClassProtocol):
+        path_params_model = path_params_constructor  # type: ignore
+        payload_model = payload_constructor  # type: ignore
+        response_model = response_model_type
+
+        @staticmethod
+        def create_url(
+            *args: PathParamsSpec.args,
+            **kwargs: PathParamsSpec.kwargs,
+        ) -> str:
+            """Create URL from path parameters."""
+            path_model = EndpointClass.path_params_model(*args, **kwargs)
+            path_dict = path_model.model_dump(**dump_options)
+
+            # Extract expected path parameters from template
+            template_params = [
+                fname
+                for _, fname, _, _ in Formatter().parse(url_template.template)
+                if fname is not None
+            ]
+
+            # Verify all required path parameters are present
+            missing_params = [
+                param for param in template_params if param not in path_dict
+            ]
+            if missing_params:
+                raise ValueError(f"Missing path parameters: {missing_params}")
+
+            return url_template.substitute(**path_dict)
+
+        @staticmethod
+        def create_url_from_model(path_params: PathParamsType) -> str:
+            return url_template.substitute(**path_params.model_dump(**dump_options))
+
+        @staticmethod
+        def create_payload(
+            *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
+        ) -> dict[str, Any]:
+            """Create request body payload."""
+            request_model = EndpointClass.payload_model(*args, **kwargs)
+            return request_model.model_dump(**dump_options)
+
+        @staticmethod
+        def create_payload_from_model(payload: PayloadType) -> dict[str, Any]:
+            return payload.model_dump(**dump_options)
+
+        @staticmethod
+        def handle_response(response: dict[str, Any]) -> ResponseType:
+            return EndpointClass.response_model.model_validate(response)
+
+        @staticmethod
+        def request_method() -> EndpointMethods:
+            return method
+
+    return EndpointClass
+
+
+if __name__ == "__main__":
+    # Example models
+    class GetUserPathParams(BaseModel):
+        """Path parameters for the user endpoint."""
+
+        user_id: int
+
+    class GetUserRequestBody(BaseModel):
+        """Request body/query parameters for the user endpoint."""
+
+        include_profile: bool = False
+
+    class UserResponse(BaseModel):
+        """Response model for user data."""
+
+        id: int
+        name: str
+
+    # Example usage of make_endpoint_class
+    UserEndpoint = build_endpoint_class(
+        url_template=Template("/users/${user_id}"),
+        path_params_constructor=GetUserPathParams,
+        payload_constructor=GetUserRequestBody,
+        response_model_type=UserResponse,
+        method=EndpointMethods.GET,
+    )
+
+    # Create URL from path parameters
+    url = UserEndpoint.create_url(user_id=123)
+    print(f"URL: {url}")
+
+    # Create payload from request body parameters
+    payload = UserEndpoint.create_payload(include_profile=True)
+    print(f"Payload: {payload}")
+
+    # Create response from endpoint
+    response = UserEndpoint.handle_response(
+        {
+            "id": 123,
+            "name": "John Doe",
+        }
+    )
+    print(f"Response: {response}")

unique_toolkit-0.8.44/unique_toolkit/_common/endpoint_requestor.py

@@ -0,0 +1,186 @@
+from enum import StrEnum
+from typing import Any, Callable, Generic, Protocol, TypeVar
+
+from pydantic import BaseModel
+from typing_extensions import ParamSpec
+
+from unique_toolkit._common.endpoint_builder import (
+    EndpointClassProtocol,
+    EndpointMethods,
+    PathParamsSpec,
+    PathParamsType,
+    PayloadParamSpec,
+    PayloadType,
+    ResponseType,
+)
+
+# Paramspecs
+CombinedParamsSpec = ParamSpec("CombinedParamsSpec")
+
+# Type variables
+CombinedParamsType = TypeVar("CombinedParamsType", bound=BaseModel)
+
+
+class EndpointRequestorProtocol(Protocol, Generic[CombinedParamsSpec, ResponseType]):
+    @classmethod
+    def request(
+        cls,
+        headers: dict[str, str],
+        *args: CombinedParamsSpec.args,
+        **kwargs: CombinedParamsSpec.kwargs,
+    ) -> ResponseType: ...
+
+
+def build_fake_requestor(
+    endpoint_type: type[
+        EndpointClassProtocol[
+            PathParamsSpec,
+            PathParamsType,
+            PayloadParamSpec,
+            PayloadType,
+            ResponseType,
+        ]
+    ],
+    combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
+    return_value: dict[str, Any],
+) -> type[EndpointRequestorProtocol[CombinedParamsSpec, ResponseType]]:
+    class FakeRequestor(EndpointRequestorProtocol):
+        _endpoint = endpoint_type
+
+        @classmethod
+        def request(
+            cls,
+            headers: dict[str, str],
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            try:
+                combined_model(*args, **kwargs)
+            except Exception as e:
+                raise ValueError(
+                    f"Invalid parameters passed to combined model {combined_model.__name__}: {e}"
+                )
+
+            return cls._endpoint.handle_response(return_value)
+
+    return FakeRequestor
+
+
+def build_request_requestor(
+    endpoint_type: type[
+        EndpointClassProtocol[
+            PathParamsSpec,
+            PathParamsType,
+            PayloadParamSpec,
+            PayloadType,
+            ResponseType,
+        ]
+    ],
+    combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
+) -> type[EndpointRequestorProtocol]:
+    import requests
+
+    class RequestRequestor(EndpointRequestorProtocol):
+        _endpoint = endpoint_type
+
+        @classmethod
+        def request(
+            cls,
+            headers: dict[str, str],
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            url = cls._endpoint.create_url_from_model(combined_model(*args, **kwargs))
+            payload = cls._endpoint.create_payload_from_model(
+                combined_model(*args, **kwargs)
+            )
+
+            response = requests.request(
+                method=cls._endpoint.request_method(),
+                url=url,
+                headers=headers,
+                json=payload,
+            )
+            return cls._endpoint.handle_response(response.json())
+
+    return RequestRequestor
+
+
+class RequestorType(StrEnum):
+    REQUESTS = "requests"
+    FAKE = "fake"
+
+
+def build_requestor(
+    requestor_type: RequestorType,
+    endpoint_type: type[
+        EndpointClassProtocol[
+            PathParamsSpec,
+            PathParamsType,
+            PayloadParamSpec,
+            PayloadType,
+            ResponseType,
+        ]
+    ],
+    combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
+    return_value: dict[str, Any] | None = None,
+    **kwargs: Any,
+) -> type[EndpointRequestorProtocol]:
+    match requestor_type:
+        case RequestorType.REQUESTS:
+            return build_request_requestor(
+                endpoint_type=endpoint_type, combined_model=combined_model
+            )
+        case RequestorType.FAKE:
+            if return_value is None:
+                raise ValueError("return_value is required for fake requestor")
+            return build_fake_requestor(
+                endpoint_type=endpoint_type,
+                combined_model=combined_model,
+                return_value=return_value,
+            )
+
+
+if __name__ == "__main__":
+    from string import Template
+
+    from unique_toolkit._common.endpoint_builder import build_endpoint_class
+
+    class GetUserPathParams(BaseModel):
+        user_id: int
+
+    class GetUserRequestBody(BaseModel):
+        include_profile: bool = False
+
+    class UserResponse(BaseModel):
+        id: int
+        name: str
+
+    class CombinedParams(GetUserPathParams, GetUserRequestBody):
+        pass
+
+    UserEndpoint = build_endpoint_class(
+        method=EndpointMethods.GET,
+        url_template=Template("https://api.example.com/users/{user_id}"),
+        path_params_constructor=GetUserPathParams,
+        payload_constructor=GetUserRequestBody,
+        response_model_type=UserResponse,
+    )
+
+    FakeUserRequestor = build_fake_requestor(
+        endpoint_type=UserEndpoint,
+        combined_model=CombinedParams,
+        return_value={"id": 100, "name": "John Doe"},
+    )
+
+    # Note that the return value is a pydantic UserResponse object
+    response = FakeUserRequestor().request(
+        headers={"a": "b"},
+        user_id=123,
+        include_profile=True,
+    )
+
+    print(response.model_dump())
+    print(response.model_json_schema())
+    print(response.id)
+    print(response.name)

unique_toolkit-0.8.43/unique_toolkit/_common/endpoint_builder.py

@@ -1,145 +0,0 @@
-"""
-This module provides a minimal framework for building endpoint classes such that a client can use
-the endpoints without having to know the details of the endpoints.
-"""
-
-from collections.abc import Callable
-from string import Formatter, Template
-from typing import (
-    Any,
-    Generic,
-    ParamSpec,
-    Protocol,
-    TypeVar,
-)
-
-from pydantic import BaseModel
-
-# Type variables
-ResponseType = TypeVar("ResponseType", bound=BaseModel)
-PathParamsType = TypeVar("PathParamsType", bound=BaseModel)
-RequestBodyType = TypeVar("RequestBodyType", bound=BaseModel)
-
-# ParamSpecs for function signatures
-RequestConstructorSpec = ParamSpec("RequestConstructorSpec")
-PathParamsSpec = ParamSpec("PathParamsSpec")
-RequestBodySpec = ParamSpec("RequestBodySpec")
-
-
-# Necessary for typing of make_endpoint_class
-class EndpointClassProtocol(Protocol, Generic[PathParamsSpec, RequestBodySpec]):
-    @staticmethod
-    def create_url(
-        *args: PathParamsSpec.args, **kwargs: PathParamsSpec.kwargs
-    ) -> str: ...
-
-    @staticmethod
-    def create_payload(
-        *args: RequestBodySpec.args, **kwargs: RequestBodySpec.kwargs
-    ) -> dict[str, Any]: ...
-
-
-# Model for any client to implement
-class Client(Protocol):
-    def request(
-        self,
-        endpoint: EndpointClassProtocol,
-    ) -> dict[str, Any]: ...
-
-
-def build_endpoint_class(
-    *,
-    url_template: Template,
-    path_params_model: Callable[PathParamsSpec, PathParamsType],
-    payload_model: Callable[RequestBodySpec, RequestBodyType],
-    response_model: type[ResponseType],
-    dump_options: dict | None = None,
-) -> type[EndpointClassProtocol[PathParamsSpec, RequestBodySpec]]:
-    """Generate a class with static methods for endpoint handling.
-
-    Uses separate models for path parameters and request body for clean API design.
-
-    Returns a class with static methods:
-    - create_url: Creates URL from path parameters
-    - create_payload: Creates request body payload
-    """
-    if not dump_options:
-        dump_options = {
-            "exclude_unset": True,
-            "by_alias": True,
-            "exclude_defaults": True,
-        }
-
-    class EndpointClass(EndpointClassProtocol):
-        @staticmethod
-        def create_url(
-            *args: PathParamsSpec.args, **kwargs: PathParamsSpec.kwargs
-        ) -> str:
-            """Create URL from path parameters."""
-            path_model = path_params_model(*args, **kwargs)
-            path_dict = path_model.model_dump(**dump_options)
-
-            # Extract expected path parameters from template
-            template_params = [
-                fname
-                for _, fname, _, _ in Formatter().parse(url_template.template)
-                if fname is not None
-            ]
-
-            # Verify all required path parameters are present
-            missing_params = [
-                param for param in template_params if param not in path_dict
-            ]
-            if missing_params:
-                raise ValueError(f"Missing path parameters: {missing_params}")
-
-            return url_template.substitute(**path_dict)
-
-        @staticmethod
-        def create_payload(
-            *args: RequestBodySpec.args, **kwargs: RequestBodySpec.kwargs
-        ) -> dict[str, Any]:
-            """Create request body payload."""
-            request_model = payload_model(*args, **kwargs)
-            return request_model.model_dump(**dump_options)
-
-        @staticmethod
-        def handle_response(response: dict[str, Any]) -> ResponseType:
-            return response_model.model_validate(response)
-
-    return EndpointClass
-
-
-if __name__ == "__main__":
-    # Example models
-    class GetUserPathParams(BaseModel):
-        """Path parameters for the user endpoint."""
-
-        user_id: int
-
-    class GetUserRequestBody(BaseModel):
-        """Request body/query parameters for the user endpoint."""
-
-        include_profile: bool = False
-
-    class UserResponse(BaseModel):
-        """Response model for user data."""
-
-        id: int
-        name: str
-
-    # Example usage of make_endpoint_class
-    UserEndpoint = build_endpoint_class(
-        url_template=Template("/users/${user_id}"),
-        path_params_model=GetUserPathParams,
-        payload_model=GetUserRequestBody,
-        response_model=UserResponse,
-    )
-
-    # Create URL from path parameters
-    url = UserEndpoint.create_url(user_id=123)
-    print(f"URL: {url}")
-
-    # Create payload from request body parameters
-    payload = UserEndpoint.create_payload(include_profile=True)
-    print(f"Payload: {payload}")