clientx 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clientx/__init__.py +39 -0
- clientx/_arguments.py +65 -0
- clientx/_builder.py +429 -0
- clientx/_class_setup.py +252 -0
- clientx/_client.py +300 -0
- clientx/_decoding.py +240 -0
- clientx/_endpoint.py +276 -0
- clientx/_method.py +198 -0
- clientx/_planner.py +1281 -0
- clientx/_registry.py +32 -0
- clientx/_signature.py +312 -0
- clientx/_tools.py +440 -0
- clientx/_types.py +313 -0
- clientx/_version.py +5 -0
- clientx/arguments.py +60 -0
- clientx/exceptions.py +61 -0
- clientx/method.py +16 -0
- clientx/py.typed +0 -0
- clientx/tools.py +23 -0
- clientx-0.1.0.dist-info/METADATA +176 -0
- clientx-0.1.0.dist-info/RECORD +23 -0
- clientx-0.1.0.dist-info/WHEEL +4 -0
- clientx-0.1.0.dist-info/licenses/LICENSE +21 -0
clientx/_method.py
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
import warnings
|
|
2
|
+
from collections.abc import Callable, Coroutine
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from functools import wraps
|
|
5
|
+
from typing import Any, Concatenate, Protocol, cast, overload
|
|
6
|
+
|
|
7
|
+
from httpx2 import USE_CLIENT_DEFAULT, Response, Timeout
|
|
8
|
+
|
|
9
|
+
from clientx._client import AsyncClientX, AsyncResource, ClientX, EndpointOwner, Resource, client_of
|
|
10
|
+
from clientx._decoding import adecode, araise_status_error, decode, raise_status_error
|
|
11
|
+
from clientx._endpoint import Endpoint
|
|
12
|
+
from clientx._registry import register_endpoint_function
|
|
13
|
+
from clientx._signature import inspect_signature
|
|
14
|
+
from clientx._types import Decoder, MethodType, UseClientDefault
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
# --- What type checkers see ---------------------------------------------------
|
|
18
|
+
class EndpointDecorator(Protocol):
|
|
19
|
+
"""The decorator a verb returns without ``decoder=``.
|
|
20
|
+
|
|
21
|
+
The endpoint keeps its signature. Each overload is limited to its kind of
|
|
22
|
+
class: a ``def`` endpoint on a ``ClientX`` or ``Resource``, an ``async def``
|
|
23
|
+
one on an ``AsyncClientX`` or ``AsyncResource``. So a ``def`` endpoint on an
|
|
24
|
+
async class is reported. An ``async def`` endpoint on a sync class isn't: to
|
|
25
|
+
a type checker it's a ``def`` that returns a coroutine, so only the check
|
|
26
|
+
when the class is defined catches it. The ``def`` overload is repeated last,
|
|
27
|
+
as in ``DecodedEndpointDecorator``.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
@overload
|
|
31
|
+
def __call__[Owner: ClientX | Resource, **P, R](
|
|
32
|
+
self, func: Callable[Concatenate[Owner, P], R], /
|
|
33
|
+
) -> Callable[Concatenate[Owner, P], R]: ...
|
|
34
|
+
@overload
|
|
35
|
+
def __call__[Owner: AsyncClientX | AsyncResource, **P, R](
|
|
36
|
+
self, func: Callable[Concatenate[Owner, P], Coroutine[Any, Any, R]], /
|
|
37
|
+
) -> Callable[Concatenate[Owner, P], Coroutine[Any, Any, R]]: ...
|
|
38
|
+
@overload
|
|
39
|
+
def __call__[Owner: ClientX | Resource, **P, R](
|
|
40
|
+
self, func: Callable[Concatenate[Owner, P], R], /
|
|
41
|
+
) -> Callable[Concatenate[Owner, P], R]: ...
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class DecodedEndpointDecorator[D](Protocol):
|
|
45
|
+
"""The decorator a verb returns with ``decoder=``.
|
|
46
|
+
|
|
47
|
+
A ``def`` endpoint must return ``D``, the decoder's return type, and an
|
|
48
|
+
``async def`` endpoint's coroutine must return it, so type checkers report
|
|
49
|
+
an endpoint whose annotation doesn't match its decoder. Each overload is
|
|
50
|
+
limited to its kind of class: if both could match, as when ``D`` is ``Any``,
|
|
51
|
+
mypy would see the endpoint as untyped.
|
|
52
|
+
|
|
53
|
+
The ``def`` overload comes first and again last: when none matches, mypy
|
|
54
|
+
reports the first overload's error and pyright the last's, so both name the
|
|
55
|
+
``def`` form, the common case.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
@overload
|
|
59
|
+
def __call__[Owner: ClientX | Resource, **P](
|
|
60
|
+
self, func: Callable[Concatenate[Owner, P], D], /
|
|
61
|
+
) -> Callable[Concatenate[Owner, P], D]: ...
|
|
62
|
+
@overload
|
|
63
|
+
def __call__[Owner: AsyncClientX | AsyncResource, **P](
|
|
64
|
+
self, func: Callable[Concatenate[Owner, P], Coroutine[Any, Any, D]], /
|
|
65
|
+
) -> Callable[Concatenate[Owner, P], Coroutine[Any, Any, D]]: ...
|
|
66
|
+
@overload
|
|
67
|
+
def __call__[Owner: ClientX | Resource, **P](
|
|
68
|
+
self, func: Callable[Concatenate[Owner, P], D], /
|
|
69
|
+
) -> Callable[Concatenate[Owner, P], D]: ...
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
# --- The verb decorators ------------------------------------------------------
|
|
73
|
+
@dataclass(frozen=True, slots=True)
|
|
74
|
+
class Method:
|
|
75
|
+
"""An HTTP verb's endpoint decorator, such as ``method.get``."""
|
|
76
|
+
|
|
77
|
+
method: MethodType
|
|
78
|
+
|
|
79
|
+
@overload
|
|
80
|
+
def __call__(
|
|
81
|
+
self,
|
|
82
|
+
path: str = "",
|
|
83
|
+
*,
|
|
84
|
+
decoder: None = None,
|
|
85
|
+
stream: bool = False,
|
|
86
|
+
deprecated: str | None = None,
|
|
87
|
+
tags: list[str] | None = None,
|
|
88
|
+
timeout: Timeout | float | None | UseClientDefault = USE_CLIENT_DEFAULT,
|
|
89
|
+
raise_for_status: bool | None = None,
|
|
90
|
+
) -> EndpointDecorator: ...
|
|
91
|
+
@overload
|
|
92
|
+
def __call__[D](
|
|
93
|
+
self,
|
|
94
|
+
path: str = "",
|
|
95
|
+
*,
|
|
96
|
+
decoder: Callable[[Response], D],
|
|
97
|
+
stream: bool = False,
|
|
98
|
+
deprecated: str | None = None,
|
|
99
|
+
tags: list[str] | None = None,
|
|
100
|
+
timeout: Timeout | float | None | UseClientDefault = USE_CLIENT_DEFAULT,
|
|
101
|
+
raise_for_status: bool | None = None,
|
|
102
|
+
) -> DecodedEndpointDecorator[D]: ...
|
|
103
|
+
def __call__(
|
|
104
|
+
self,
|
|
105
|
+
path: str = "",
|
|
106
|
+
*,
|
|
107
|
+
decoder: Decoder | None = None,
|
|
108
|
+
stream: bool = False,
|
|
109
|
+
deprecated: str | None = None,
|
|
110
|
+
tags: list[str] | None = None,
|
|
111
|
+
timeout: Timeout | float | None | UseClientDefault = USE_CLIENT_DEFAULT,
|
|
112
|
+
raise_for_status: bool | None = None,
|
|
113
|
+
) -> Any:
|
|
114
|
+
"""Return the decorator that turns a method into an endpoint.
|
|
115
|
+
|
|
116
|
+
Without ``decoder=``, the endpoint keeps its own signature. With one, it
|
|
117
|
+
must return what the decoder returns: type checkers report a mismatch at
|
|
118
|
+
the decorator.
|
|
119
|
+
|
|
120
|
+
Args:
|
|
121
|
+
path: The path template, such as ``"/users/{user_id}"``, relative to
|
|
122
|
+
the client's base URL. A resource joins its prefix onto it.
|
|
123
|
+
decoder: Turns the ``httpx2.Response`` into the return value, in
|
|
124
|
+
place of the decoding the return annotation implies. A generator
|
|
125
|
+
decoder streams, for an endpoint annotated ``-> Iterator[...]``
|
|
126
|
+
(an async generator for ``-> AsyncIterator[...]``).
|
|
127
|
+
stream: Return the open, unread response, which the caller reads and
|
|
128
|
+
closes. Only with ``-> Response`` and no ``decoder=``.
|
|
129
|
+
deprecated: The message of a ``DeprecationWarning`` each call emits.
|
|
130
|
+
tags: Labels that group endpoints, each kept once. A resource's tags
|
|
131
|
+
go in front. ClientX doesn't use them itself yet.
|
|
132
|
+
timeout: The request timeout, as httpx2 takes it: the default uses
|
|
133
|
+
the client's, and ``None`` turns it off.
|
|
134
|
+
raise_for_status: Whether a 4xx or 5xx response raises
|
|
135
|
+
``httpx2.HTTPStatusError``; ``None`` uses the client's setting.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
def decorator[T: EndpointOwner, **P, R](func: Callable[Concatenate[T, P], R]) -> Callable[Concatenate[T, P], R]:
|
|
139
|
+
endpoint = Endpoint(
|
|
140
|
+
method=self.method,
|
|
141
|
+
raw_path=path,
|
|
142
|
+
signature=inspect_signature(func),
|
|
143
|
+
tags=list(tags or ()),
|
|
144
|
+
timeout=timeout,
|
|
145
|
+
raise_for_status=raise_for_status,
|
|
146
|
+
decoder=decoder,
|
|
147
|
+
stream_response=stream,
|
|
148
|
+
deprecated=deprecated,
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
@wraps(func)
|
|
152
|
+
def wrapper(_self: T, /, *args: P.args, **kwargs: P.kwargs) -> R:
|
|
153
|
+
if endpoint.deprecated is not None:
|
|
154
|
+
# `stacklevel=2` names the caller's line. The warning must
|
|
155
|
+
# stay in the wrapper's own frame.
|
|
156
|
+
warnings.warn(endpoint.deprecated, DeprecationWarning, stacklevel=2)
|
|
157
|
+
client = client_of(_self, ClientX)
|
|
158
|
+
bound = endpoint.bind(_self, *args, **kwargs)
|
|
159
|
+
url, request_arguments = endpoint.request_arguments(bound)
|
|
160
|
+
request = client.build_request(endpoint.method, url, **request_arguments)
|
|
161
|
+
response = client.send(request, stream=endpoint.stream)
|
|
162
|
+
if response.is_error and _raises_for_status(endpoint, client):
|
|
163
|
+
raise_status_error(response)
|
|
164
|
+
if endpoint.stream_response:
|
|
165
|
+
return cast(R, response) # Open and unread: the caller reads and closes it.
|
|
166
|
+
return cast(R, decode(endpoint.decoder, response, stream=endpoint.stream))
|
|
167
|
+
|
|
168
|
+
@wraps(func)
|
|
169
|
+
async def async_wrapper(_self: T, /, *args: P.args, **kwargs: P.kwargs) -> object:
|
|
170
|
+
if endpoint.deprecated is not None:
|
|
171
|
+
warnings.warn(endpoint.deprecated, DeprecationWarning, stacklevel=2)
|
|
172
|
+
client = client_of(_self, AsyncClientX)
|
|
173
|
+
bound = endpoint.bind(_self, *args, **kwargs)
|
|
174
|
+
url, request_arguments = endpoint.request_arguments(bound)
|
|
175
|
+
request = client.build_request(endpoint.method, url, **request_arguments)
|
|
176
|
+
response = await client.send(request, stream=endpoint.stream)
|
|
177
|
+
if response.is_error and _raises_for_status(endpoint, client):
|
|
178
|
+
await araise_status_error(response)
|
|
179
|
+
if endpoint.stream_response:
|
|
180
|
+
return response # Open and unread: the caller reads and closes it.
|
|
181
|
+
return await adecode(endpoint.decoder, response, stream=endpoint.stream)
|
|
182
|
+
|
|
183
|
+
endpoint_function = (
|
|
184
|
+
cast(Callable[Concatenate[T, P], R], async_wrapper) if endpoint.signature.is_async else wrapper
|
|
185
|
+
)
|
|
186
|
+
register_endpoint_function(endpoint_function, endpoint)
|
|
187
|
+
return endpoint_function
|
|
188
|
+
|
|
189
|
+
return decorator
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _raises_for_status(endpoint: Endpoint, client: ClientX | AsyncClientX) -> bool:
|
|
193
|
+
"""Return whether ``endpoint`` raises for a 4xx or 5xx response.
|
|
194
|
+
|
|
195
|
+
Its own setting, if it has one, wins over the client's. Not ``or``: an
|
|
196
|
+
endpoint's ``False`` must win over the client's ``True``.
|
|
197
|
+
"""
|
|
198
|
+
return client.__clientx_raise_for_status__ if endpoint.raise_for_status is None else endpoint.raise_for_status
|