unique_toolkit 0.8.42__py3-none-any.whl → 0.8.44__py3-none-any.whl

unique_toolkit/_common/endpoint_builder.py

@@ -3,10 +3,11 @@ This module provides a minimal framework for building endpoint classes such that
 the endpoints without having to know the details of the endpoints.
 """
 
-from collections.abc import Callable
+from enum import StrEnum
 from string import Formatter, Template
 from typing import (
     Any,
+    Callable,
     Generic,
     ParamSpec,
     Protocol,
@@ -15,46 +16,87 @@ from typing import (
 
 from pydantic import BaseModel
 
+# Paramspecs
+PayloadParamSpec = ParamSpec("PayloadParamSpec")
+PathParamsSpec = ParamSpec("PathParamsSpec")
+
 # Type variables
-ResponseType = TypeVar("ResponseType", bound=BaseModel)
+ResponseType = TypeVar("ResponseType", bound=BaseModel, covariant=True)
 PathParamsType = TypeVar("PathParamsType", bound=BaseModel)
-RequestBodyType = TypeVar("RequestBodyType", bound=BaseModel)
+PayloadType = TypeVar("PayloadType", bound=BaseModel)
 
-# ParamSpecs for function signatures
-RequestConstructorSpec = ParamSpec("RequestConstructorSpec")
-PathParamsSpec = ParamSpec("PathParamsSpec")
-RequestBodySpec = ParamSpec("RequestBodySpec")
+# 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, RequestBodySpec]):
+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: RequestBodySpec.args, **kwargs: RequestBodySpec.kwargs
+        *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
     ) -> dict[str, Any]: ...
 
+    @staticmethod
+    def create_payload_from_model(payload: PayloadType) -> dict[str, Any]: ...
 
-# Model for any client to implement
-class Client(Protocol):
-    def request(
-        self,
-        endpoint: EndpointClassProtocol,
-    ) -> 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_model: Callable[PathParamsSpec, PathParamsType],
-    payload_model: Callable[RequestBodySpec, RequestBodyType],
-    response_model: type[ResponseType],
+    path_params_constructor: Callable[PathParamsSpec, PathParamsType],
+    payload_constructor: Callable[PayloadParamSpec, PayloadType],
+    response_model_type: type[ResponseType],
     dump_options: dict | None = None,
-) -> type[EndpointClassProtocol[PathParamsSpec, RequestBodySpec]]:
+) -> 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.
@@ -63,6 +105,13 @@ def build_endpoint_class(
     - 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,
@@ -71,12 +120,17 @@ def build_endpoint_class(
         }
 
     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
+            *args: PathParamsSpec.args,
+            **kwargs: PathParamsSpec.kwargs,
         ) -> str:
             """Create URL from path parameters."""
-            path_model = path_params_model(*args, **kwargs)
+            path_model = EndpointClass.path_params_model(*args, **kwargs)
             path_dict = path_model.model_dump(**dump_options)
 
             # Extract expected path parameters from template
@@ -95,17 +149,29 @@ def build_endpoint_class(
 
             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: RequestBodySpec.args, **kwargs: RequestBodySpec.kwargs
+            *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
         ) -> dict[str, Any]:
             """Create request body payload."""
-            request_model = payload_model(*args, **kwargs)
+            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 response_model.model_validate(response)
+            return EndpointClass.response_model.model_validate(response)
+
+        @staticmethod
+        def request_method() -> EndpointMethods:
+            return method
 
     return EndpointClass
 
@@ -131,9 +197,10 @@ if __name__ == "__main__":
     # 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,
+        path_params_constructor=GetUserPathParams,
+        payload_constructor=GetUserRequestBody,
+        response_model_type=UserResponse,
+        method=EndpointMethods.GET,
     )
 
     # Create URL from path parameters
@@ -143,3 +210,12 @@ if __name__ == "__main__":
     # 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/_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/app/unique_settings.py

@@ -68,7 +68,11 @@ class UniqueApi(BaseSettings):
         default="http://localhost:8092/",
         description="The base URL of the Unique API. Ask your admin to provide you with the correct URL.",
         validation_alias=AliasChoices(
-            "unique_api_base_url", "base_url", "UNIQUE_API_BASE_URL", "BASE_URL"
+            "unique_api_base_url",
+            "base_url",
+            "UNIQUE_API_BASE_URL",
+            "BASE_URL",
+            "API_BASE",
         ),
     )
     version: str = Field(

{unique_toolkit-0.8.42.dist-info → unique_toolkit-0.8.44.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 0.8.42
+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,12 @@ 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`
+
 ## [0.8.42] - 2025-09-02
 - updated schema of `chunk_relevancy_sorter`
 

{unique_toolkit-0.8.42.dist-info → unique_toolkit-0.8.44.dist-info}/RECORD

@@ -8,7 +8,8 @@ unique_toolkit/_common/chunk_relevancy_sorter/schemas.py,sha256=doAWPPx8d0zIqHMX
 unique_toolkit/_common/chunk_relevancy_sorter/service.py,sha256=UxYn4xJMNEXQ1afMiT2sMwXgdmlFNPaglVhx6CRRtiM,13864
 unique_toolkit/_common/chunk_relevancy_sorter/tests/test_service.py,sha256=JRvLtJXPmz6bm1tFSSqt01HHVeanSD8zk70XVLJHOEM,8878
 unique_toolkit/_common/default_language_model.py,sha256=tmHSqg6e8G7RmKqmdE_tmLxkSN0x-aGoyUdy6Pl2oAE,334
-unique_toolkit/_common/endpoint_builder.py,sha256=oM6uDmxUqTAJut6MuJQj3bIX4yOccyErWD5bJ1d1lcY,4526
+unique_toolkit/_common/endpoint_builder.py,sha256=zZFEeMAHySWh2AU-nuufT7iNd0NT54qA6AAxNEVDZb0,6635
+unique_toolkit/_common/endpoint_requestor.py,sha256=q-H4kT2Ip63omsodMZ8Bgo3HLMFhnOpaGoc2MqIZdmI,5317
 unique_toolkit/_common/exception.py,sha256=caQIE1btsQnpKCHqL2cgWUSbHup06enQu_Pt7uGUTTE,727
 unique_toolkit/_common/feature_flags/schema.py,sha256=3JpTuld8kK-UQ5B0sbYTu0yqhyFPnChXG2Iv4BNqHdg,539
 unique_toolkit/_common/pydantic_helpers.py,sha256=4a8LPey31k4dCztYag1OBhYnGHREN08-l3NEjbFD1ok,743
@@ -24,7 +25,7 @@ unique_toolkit/app/init_sdk.py,sha256=5_oDoETr6akwYyBCb0ivTdMNu3SVgPSkrXcDS6ELyY
 unique_toolkit/app/performance/async_tasks.py,sha256=H0l3OAcosLwNHZ8d2pd-Di4wHIXfclEvagi5kfqLFPA,1941
 unique_toolkit/app/performance/async_wrapper.py,sha256=yVVcRDkcdyfjsxro-N29SBvi-7773wnfDplef6-y8xw,1077
 unique_toolkit/app/schemas.py,sha256=xHdzMyZ_cgCzxCqzCJYwOCAYWkaQ9zIyZsRhDgSQnEA,8088
-unique_toolkit/app/unique_settings.py,sha256=_Ll_GuWYiOIK2w4HQPA_uopTdDDFcjVqDFO3m2F2b-Q,10254
+unique_toolkit/app/unique_settings.py,sha256=3BSMRAUz2rfbmIW5Ot-xXj7hMjWwtNskbUh9joh11mE,10315
 unique_toolkit/app/verification.py,sha256=GxFFwcJMy25fCA_Xe89wKW7bgqOu8PAs5y8QpHF0GSc,3861
 unique_toolkit/chat/__init__.py,sha256=LRs2G-JTVuci4lbtHTkVUiNcZcSR6uqqfnAyo7af6nY,619
 unique_toolkit/chat/constants.py,sha256=05kq6zjqUVB2d6_P7s-90nbljpB3ryxwCI-CAz0r2O4,83
@@ -131,7 +132,7 @@ unique_toolkit/tools/utils/execution/execution.py,sha256=vjG2Y6awsGNtlvyQAGCTthQ
 unique_toolkit/tools/utils/source_handling/schema.py,sha256=vzAyf6ZWNexjMO0OrnB8y2glGkvAilmGGQXd6zcDaKw,870
 unique_toolkit/tools/utils/source_handling/source_formatting.py,sha256=C7uayNbdkNVJdEARA5CENnHtNY1SU6etlaqbgHNyxaQ,9152
 unique_toolkit/tools/utils/source_handling/tests/test_source_formatting.py,sha256=oM5ZxEgzROrnX1229KViCAFjRxl9wCTzWZoinYSHleM,6979
-unique_toolkit-0.8.42.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
-unique_toolkit-0.8.42.dist-info/METADATA,sha256=QQPAhHh0vIc_d9P6DrmlSBSkhVLnCmqs8mFjVlPyHc4,30418
-unique_toolkit-0.8.42.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-unique_toolkit-0.8.42.dist-info/RECORD,,
+unique_toolkit-0.8.44.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
+unique_toolkit-0.8.44.dist-info/METADATA,sha256=qgsVibZKJU2Colr_5lqRIr2glNjV_48wFO_xqjnskF0,30583
+unique_toolkit-0.8.44.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+unique_toolkit-0.8.44.dist-info/RECORD,,