typact 0.2.0__tar.gz → 0.2.1__tar.gz

{typact-0.2.0/src/typact.egg-info → typact-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typact
-Version: 0.2.0
+Version: 0.2.1
 Summary: Add your description here
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -257,6 +257,29 @@ client = HttpClient(
 )
 ```
 
+单个接口可覆盖 Client 默认策略；显式传入 `None` 可关闭该默认值：
+
+```python
+from collections.abc import AsyncIterator
+
+from typact import Path
+
+@client.get(
+    "/reports/{report_id}",
+    timeout=60,
+    retry_config=RetryConfig(max_retries=2),
+)
+async def get_report(report_id: int = Path()) -> dict:
+    pass
+
+
+@client.get("/events", timeout=None)
+async def events() -> AsyncIterator[dict]:
+    pass
+```
+
+流式连接只会在尚未产出任何分片前重试，避免重复交付 SSE 事件或下载数据。
+
 所有 Runtime 都可以映射为统一的 `typact.Response`：
 
 ```python

{typact-0.2.0 → typact-0.2.1}/README.md

@@ -242,6 +242,29 @@ client = HttpClient(
 )
 ```
 
+单个接口可覆盖 Client 默认策略；显式传入 `None` 可关闭该默认值：
+
+```python
+from collections.abc import AsyncIterator
+
+from typact import Path
+
+@client.get(
+    "/reports/{report_id}",
+    timeout=60,
+    retry_config=RetryConfig(max_retries=2),
+)
+async def get_report(report_id: int = Path()) -> dict:
+    pass
+
+
+@client.get("/events", timeout=None)
+async def events() -> AsyncIterator[dict]:
+    pass
+```
+
+流式连接只会在尚未产出任何分片前重试，避免重复交付 SSE 事件或下载数据。
+
 所有 Runtime 都可以映射为统一的 `typact.Response`：
 
 ```python

{typact-0.2.0 → typact-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typact"
-version = "0.2.0"
+version = "0.2.1"
 description = "Add your description here"
 readme = "README.md"
 license = "MIT"

{typact-0.2.0 → typact-0.2.1}/src/typact/client/decorator.py

@@ -5,7 +5,8 @@ from collections.abc import AsyncIterator
 from functools import wraps
 from typing import Any, AsyncGenerator, Callable, get_origin, get_type_hints
 
-from typact.client.metadata import RouteDefinition
+from typact.client.metadata import UNSET, RouteDefinition
+from typact.core.retry import RetryConfig
 
 
 def run_async_from_sync(coro_factory: Callable[[], Any]):
@@ -33,7 +34,17 @@ def run_async_from_sync(coro_factory: Callable[[], Any]):
     return result[0]
 
 
-def create_route_decorator(client: Any, method: str, path: str):
+def create_route_decorator(
+    client: Any,
+    method: str,
+    path: str,
+    *,
+    timeout: float | None | object = UNSET,
+    retry_config: RetryConfig | None | object = UNSET,
+):
+    if timeout is not UNSET and timeout is not None and timeout <= 0:
+        raise ValueError("timeout must be greater than 0")
+
     def decorator(func: Callable):
         route = RouteDefinition(
             method=method,
@@ -41,6 +52,8 @@ def create_route_decorator(client: Any, method: str, path: str):
             signature=inspect.signature(func),
             return_type=get_type_hints(func).get("return", Any),
             is_async=inspect.iscoroutinefunction(func),
+            timeout=timeout,
+            retry_config=retry_config,
         )
 
         is_stream = get_origin(route.return_type) in {AsyncIterator, AsyncGenerator}

{typact-0.2.0 → typact-0.2.1}/src/typact/client/http_client.py

@@ -6,11 +6,11 @@ from typing import Any, ParamSpec, TypeVar, overload
 
 from typact.builder.request_builder import RequestBuilder
 from typact.client.decorator import create_route_decorator
-from typact.client.metadata import RouteDefinition
+from typact.client.metadata import UNSET, RouteDefinition
 from typact.converter.response_converter import ResponseConverter
 from typact.converter.sse_converter import SseResponseConverter
 from typact.converter.stream_converter import StreamResponseConverter
-from typact.core.errors import TypactNetworkError, TypactTimeoutError
+from typact.core.errors import TypactHttpError, TypactNetworkError, TypactTimeoutError
 from typact.core.retry import RetryConfig
 from typact.core.types import RequestConfig, Response
 from typact.interceptor.base import InterceptorChain
@@ -49,20 +49,80 @@ class HttpClient:
         self.timeout = timeout
         self.retry_config = retry_config or RetryConfig()
 
-    def get(self, path: str):
-        return create_route_decorator(self, "GET", path)
+    def get(
+        self,
+        path: str,
+        *,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
+    ):
+        return create_route_decorator(
+            self,
+            "GET",
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
-    def post(self, path: str):
-        return create_route_decorator(self, "POST", path)
+    def post(
+        self,
+        path: str,
+        *,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
+    ):
+        return create_route_decorator(
+            self,
+            "POST",
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
-    def put(self, path: str):
-        return create_route_decorator(self, "PUT", path)
+    def put(
+        self,
+        path: str,
+        *,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
+    ):
+        return create_route_decorator(
+            self,
+            "PUT",
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
-    def patch(self, path: str):
-        return create_route_decorator(self, "PATCH", path)
+    def patch(
+        self,
+        path: str,
+        *,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
+    ):
+        return create_route_decorator(
+            self,
+            "PATCH",
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
-    def delete(self, path: str):
-        return create_route_decorator(self, "DELETE", path)
+    def delete(
+        self,
+        path: str,
+        *,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
+    ):
+        return create_route_decorator(
+            self,
+            "DELETE",
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
     @overload
     def request(
@@ -70,6 +130,8 @@ class HttpClient:
         path: str,
         *,
         method: str,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
     ) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
 
     @overload
@@ -79,6 +141,8 @@ class HttpClient:
         func: Callable[P, R],
         *,
         methods: Sequence[str],
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
     ) -> Callable[P, R]: ...
 
     def request(
@@ -88,6 +152,8 @@ class HttpClient:
         *,
         method: str | None = None,
         methods: Sequence[str] | None = None,
+        timeout: float | None | object = UNSET,
+        retry_config: RetryConfig | None | object = UNSET,
     ):
         if method is not None and methods is not None:
             raise TypeError("method and methods cannot be used together")
@@ -96,7 +162,13 @@ class HttpClient:
         if len(route_methods) != 1:
             raise ValueError("request requires exactly one HTTP method")
 
-        decorator = create_route_decorator(self, route_methods[0], path)
+        decorator = create_route_decorator(
+            self,
+            route_methods[0],
+            path,
+            timeout=timeout,
+            retry_config=retry_config,
+        )
 
         def register(route_func: Callable[P, R]) -> Callable[P, R]:
             wrapper = decorator(route_func)
@@ -117,20 +189,20 @@ class HttpClient:
         args: tuple[Any, ...],
         kwargs: dict[str, Any],
     ):
-        config = self.request_builder.build(route, args, kwargs)
-        config.timeout = self.timeout
+        config = self._build_request_config(route, args, kwargs)
         config = await self.interceptor_chain.apply_request(config)
 
-        response = await self._request_with_retry(config)
+        retry_config = self._get_retry_config(route)
+        response = await self._request_with_retry(config, retry_config)
 
         if response.status_code == 401:
-            retry_config = await self.interceptor_chain.refresh_unauthorized(
+            refreshed_config = await self.interceptor_chain.refresh_unauthorized(
                 config=config,
                 response=response,
             )
 
-            if retry_config is not None:
-                response = await self._request_with_retry(retry_config)
+            if refreshed_config is not None:
+                response = await self._request_with_retry(refreshed_config, retry_config)
 
         response = await self.interceptor_chain.apply_response(response)
 
@@ -148,10 +220,10 @@ class HttpClient:
         args: tuple[Any, ...],
         kwargs: dict[str, Any],
     ) -> AsyncIterator[Any]:
-        config = self.request_builder.build(route, args, kwargs)
-        config.timeout = self.timeout
+        config = self._build_request_config(route, args, kwargs)
         config = await self.interceptor_chain.apply_request(config)
         item_type = route.return_type.__args__[0]
+        retry_config = self._get_retry_config(route)
 
         converter = (
             self.stream_converter
@@ -159,10 +231,32 @@ class HttpClient:
             else self.sse_converter
         )
 
-        async for item in converter.convert(self.runtime.stream(config), item_type):
+        async for item in converter.convert(
+            self._stream_with_retry(config, retry_config),
+            item_type,
+        ):
             yield item
 
-    async def _request_with_retry(self, config: RequestConfig) -> Response:
+    def _build_request_config(
+        self,
+        route: RouteDefinition,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> RequestConfig:
+        config = self.request_builder.build(route, args, kwargs)
+        config.timeout = self.timeout if route.timeout is UNSET else route.timeout
+        return config
+
+    def _get_retry_config(self, route: RouteDefinition) -> RetryConfig:
+        if route.retry_config is UNSET:
+            return self.retry_config
+        return route.retry_config or RetryConfig()
+
+    async def _request_with_retry(
+        self,
+        config: RequestConfig,
+        retry_config: RetryConfig,
+    ) -> Response:
         retry_number = 0
 
         while True:
@@ -172,7 +266,7 @@ class HttpClient:
                 if not self._is_network_error(exc):
                     raise
 
-                if not self._can_retry(config, retry_number):
+                if not self._can_retry(config, retry_number, retry_config):
                     if isinstance(exc, TypactTimeoutError):
                         raise exc
                     if isinstance(exc, TimeoutError):
@@ -180,12 +274,12 @@ class HttpClient:
                     raise TypactNetworkError("Typact request failed due to a network error", cause=exc) from exc
             else:
                 if (
-                    response.status_code not in self.retry_config.retry_status_codes
-                    or not self._can_retry(config, retry_number)
+                    response.status_code not in retry_config.retry_status_codes
+                    or not self._can_retry(config, retry_number, retry_config)
                 ):
                     return response
 
-            await asyncio.sleep(self.retry_config.delay_for_retry(retry_number))
+            await asyncio.sleep(retry_config.delay_for_retry(retry_number))
             retry_number += 1
 
     async def _request_once(self, config: RequestConfig) -> Response:
@@ -198,12 +292,49 @@ class HttpClient:
         except TimeoutError as exc:
             raise TypactTimeoutError(config.timeout) from exc
 
-    def _can_retry(self, config: RequestConfig, retry_number: int) -> bool:
+    async def _stream_with_retry(
+        self,
+        config: RequestConfig,
+        retry_config: RetryConfig,
+    ) -> AsyncIterator[bytes]:
+        retry_number = 0
+
+        while True:
+            received_chunk = False
+
+            try:
+                async for chunk in self.runtime.stream(config):
+                    received_chunk = True
+                    yield chunk
+                return
+            except Exception as exc:
+                can_retry = (
+                    not received_chunk
+                    and self._can_retry(config, retry_number, retry_config)
+                    and self._is_retryable_stream_error(exc, retry_config)
+                )
+                if not can_retry:
+                    raise
+
+            await asyncio.sleep(retry_config.delay_for_retry(retry_number))
+            retry_number += 1
+
+    def _can_retry(
+        self,
+        config: RequestConfig,
+        retry_number: int,
+        retry_config: RetryConfig,
+    ) -> bool:
         return (
-            retry_number < self.retry_config.max_retries
-            and self.retry_config.allows_method(config.method)
+            retry_number < retry_config.max_retries
+            and retry_config.allows_method(config.method)
         )
 
+    def _is_retryable_stream_error(self, exc: Exception, retry_config: RetryConfig) -> bool:
+        if isinstance(exc, TypactHttpError):
+            return exc.status_code in retry_config.retry_status_codes
+        return self._is_network_error(exc)
+
     @staticmethod
     def _is_network_error(exc: Exception) -> bool:
         if isinstance(exc, TypactTimeoutError):

{typact-0.2.0 → typact-0.2.1}/src/typact/client/metadata.py

@@ -2,6 +2,11 @@ import inspect
 from dataclasses import dataclass
 from typing import Any
 
+from typact.core.retry import RetryConfig
+
+
+UNSET = object()
+
 
 @dataclass(frozen=True)
 class RouteDefinition:
@@ -10,3 +15,5 @@ class RouteDefinition:
     signature: inspect.Signature
     return_type: Any
     is_async: bool
+    timeout: float | None | object = UNSET
+    retry_config: RetryConfig | None | object = UNSET

{typact-0.2.0 → typact-0.2.1/src/typact.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typact
-Version: 0.2.0
+Version: 0.2.1
 Summary: Add your description here
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -257,6 +257,29 @@ client = HttpClient(
 )
 ```
 
+单个接口可覆盖 Client 默认策略；显式传入 `None` 可关闭该默认值：
+
+```python
+from collections.abc import AsyncIterator
+
+from typact import Path
+
+@client.get(
+    "/reports/{report_id}",
+    timeout=60,
+    retry_config=RetryConfig(max_retries=2),
+)
+async def get_report(report_id: int = Path()) -> dict:
+    pass
+
+
+@client.get("/events", timeout=None)
+async def events() -> AsyncIterator[dict]:
+    pass
+```
+
+流式连接只会在尚未产出任何分片前重试，避免重复交付 SSE 事件或下载数据。
+
 所有 Runtime 都可以映射为统一的 `typact.Response`：
 
 ```python

{typact-0.2.0 → typact-0.2.1}/tests/test_http_client_request.py

@@ -39,6 +39,23 @@ class SlowRuntime(ClientRuntime):
         return Response(status_code=200, headers={}, content=b"{}", json_data={})
 
 
+class FlakyStreamRuntime(ClientRuntime):
+    def __init__(self):
+        self.stream_attempts = 0
+
+    async def request(self, config: RequestConfig) -> Response:
+        raise NotImplementedError
+
+    def stream(self, config: RequestConfig):
+        async def iterator():
+            self.stream_attempts += 1
+            if self.stream_attempts == 1:
+                raise TypactHttpError(503, b"temporarily unavailable")
+            yield b"ready"
+
+        return iterator()
+
+
 class LoginApi:
     def __init__(self, runtime: MockRuntime):
         self.client = HttpClient("https://example.test", client_runtime=runtime)
@@ -123,6 +140,30 @@ class StreamApi:
         raise NotImplementedError
 
 
+class RoutePolicyApi:
+    def __init__(self, client: HttpClient):
+        client.request("/short", method="GET", timeout=3)(self.short)
+        client.request("/long-stream", method="GET", timeout=None)(self.long_stream)
+        client.request("/no-retry", method="GET", retry_config=None)(self.no_retry)
+        client.request(
+            "/retry-stream",
+            method="GET",
+            retry_config=RetryConfig(max_retries=1, initial_delay=0),
+        )(self.retry_stream)
+
+    async def short(self) -> dict:
+        raise NotImplementedError
+
+    async def long_stream(self) -> AsyncIterator[bytes]:
+        raise NotImplementedError
+
+    async def no_retry(self) -> dict:
+        raise NotImplementedError
+
+    async def retry_stream(self) -> AsyncIterator[bytes]:
+        raise NotImplementedError
+
+
 class HttpClientRequestTest(unittest.TestCase):
     def test_registers_bound_method_and_preserves_signature(self):
         runtime = MockRuntime()
@@ -336,6 +377,56 @@ class HttpClientRequestTest(unittest.TestCase):
 
         self.assertEqual(asyncio.run(collect()), "你好")
 
+    def test_route_timeout_overrides_client_default(self):
+        runtime = MockRuntime()
+        runtime.add_response("GET", "https://example.test/short", json_data={"ok": True})
+        api = RoutePolicyApi(HttpClient("https://example.test", client_runtime=runtime, timeout=30))
+
+        self.assertEqual(asyncio.run(api.short()), {"ok": True})
+        self.assertEqual(runtime.requests[0].timeout, 3)
+
+    def test_rejects_non_positive_route_timeout(self):
+        client = HttpClient("https://example.test")
+
+        with self.assertRaises(ValueError):
+            client.get("/short", timeout=0)
+
+    def test_route_timeout_can_disable_client_default_for_streams(self):
+        runtime = MockRuntime()
+        runtime.add_stream_response("GET", "https://example.test/long-stream", [b"first"])
+        api = RoutePolicyApi(HttpClient("https://example.test", client_runtime=runtime, timeout=30))
+
+        async def collect():
+            return [chunk async for chunk in api.long_stream()]
+
+        self.assertEqual(asyncio.run(collect()), [b"first"])
+        self.assertIsNone(runtime.requests[0].timeout)
+
+    def test_route_retry_config_can_disable_client_default(self):
+        runtime = MockRuntime()
+        runtime.add_response("GET", "https://example.test/no-retry", status_code=503)
+        api = RoutePolicyApi(
+            HttpClient(
+                "https://example.test",
+                client_runtime=runtime,
+                retry_config=RetryConfig(max_retries=1, initial_delay=0),
+            )
+        )
+
+        with self.assertRaises(TypactHttpError):
+            asyncio.run(api.no_retry())
+        self.assertEqual(len(runtime.requests), 1)
+
+    def test_stream_retries_before_delivering_a_chunk(self):
+        runtime = FlakyStreamRuntime()
+        api = RoutePolicyApi(HttpClient("https://example.test", client_runtime=runtime))
+
+        async def collect():
+            return [chunk async for chunk in api.retry_stream()]
+
+        self.assertEqual(asyncio.run(collect()), [b"ready"])
+        self.assertEqual(runtime.stream_attempts, 2)
+
 
 if __name__ == "__main__":
     unittest.main()