spec2py-runtime 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.
@@ -0,0 +1,293 @@
1
+ """Pagination strategies and page objects that iterate lazily across pages.
2
+
3
+ ::
4
+
5
+ for invoice in client.invoices.list(status="open"): # every item, every page
6
+ ...
7
+
8
+ page = client.invoices.list()
9
+ page.data, page.next_cursor # one page, for manual control
10
+ if page.has_next_page():
11
+ page = page.get_next_page()
12
+ """
13
+
14
+ import re
15
+ from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Iterator
16
+ from dataclasses import dataclass, field
17
+ from typing import Any, Protocol, cast
18
+
19
+ import httpx2
20
+
21
+ __all__ = [
22
+ "AsyncPage",
23
+ "AsyncPaginator",
24
+ "CursorPagination",
25
+ "LinkHeaderPagination",
26
+ "NextPage",
27
+ "OffsetPagination",
28
+ "Page",
29
+ "PageNumberPagination",
30
+ "PageState",
31
+ "PaginationStrategy",
32
+ "dig",
33
+ ]
34
+
35
+
36
+ def dig(body: object, path: str | None) -> object:
37
+ """Look up a dotted path (``"meta.next_cursor"``) in decoded JSON."""
38
+ if not path:
39
+ return body
40
+ current = body
41
+ for part in path.split("."):
42
+ if not isinstance(current, dict):
43
+ return None
44
+ current = cast(dict[str, object], current).get(part)
45
+ return current
46
+
47
+
48
+ @dataclass(frozen=True, slots=True)
49
+ class PageState:
50
+ """What a strategy sees about the page just fetched."""
51
+
52
+ params: dict[str, object]
53
+ body: object
54
+ headers: httpx2.Headers
55
+ items: list[object]
56
+
57
+
58
+ @dataclass(frozen=True, slots=True)
59
+ class NextPage:
60
+ """How to fetch the next page: query overrides, or a whole new URL."""
61
+
62
+ params: dict[str, object] = field(default_factory=dict[str, object])
63
+ url: str | None = None
64
+
65
+
66
+ class PaginationStrategy(Protocol):
67
+ @property
68
+ def items(self) -> str | None:
69
+ """Dotted path to the item array in the body (``None``: the body is the array)."""
70
+ ...
71
+
72
+ def next_page(self, state: PageState) -> NextPage | None: ...
73
+
74
+ def next_cursor(self, state: PageState) -> str | None: ...
75
+
76
+
77
+ def _more(state: PageState, has_more: str | None) -> bool:
78
+ if not state.items:
79
+ return False
80
+ return not (has_more and dig(state.body, has_more) is False)
81
+
82
+
83
+ @dataclass(frozen=True, slots=True)
84
+ class CursorPagination:
85
+ """Opaque cursors: ``?cursor=`` from a body field or from the last item's id."""
86
+
87
+ items: str | None = "data"
88
+ cursor_param: str = "cursor"
89
+ next_cursor_path: str | None = "next_cursor"
90
+ has_more: str | None = None
91
+ cursor_from_item: str | None = None
92
+
93
+ def next_cursor(self, state: PageState) -> str | None:
94
+ if self.cursor_from_item:
95
+ if not state.items:
96
+ return None
97
+ value = dig(state.items[-1], self.cursor_from_item)
98
+ else:
99
+ value = dig(state.body, self.next_cursor_path)
100
+ return None if value in (None, "") else str(value)
101
+
102
+ def next_page(self, state: PageState) -> NextPage | None:
103
+ if self.has_more and dig(state.body, self.has_more) is False:
104
+ return None
105
+ cursor = self.next_cursor(state)
106
+ if cursor is None:
107
+ return None
108
+ if cursor.startswith(("http://", "https://", "/")):
109
+ return NextPage(url=cursor)
110
+ return NextPage(params={self.cursor_param: cursor})
111
+
112
+
113
+ @dataclass(frozen=True, slots=True)
114
+ class OffsetPagination:
115
+ """``?offset=&limit=`` paging."""
116
+
117
+ items: str | None = "data"
118
+ offset_param: str = "offset"
119
+ limit_param: str | None = "limit"
120
+ total: str | None = None
121
+ has_more: str | None = None
122
+
123
+ def next_cursor(self, state: PageState) -> str | None:
124
+ return None
125
+
126
+ def next_page(self, state: PageState) -> NextPage | None:
127
+ if not _more(state, self.has_more):
128
+ return None
129
+ offset = int(cast(Any, state.params.get(self.offset_param)) or 0)
130
+ next_offset = offset + len(state.items)
131
+ total = dig(state.body, self.total) if self.total else None
132
+ if isinstance(total, int) and next_offset >= total:
133
+ return None
134
+ limit = state.params.get(self.limit_param) if self.limit_param else None
135
+ if total is None and isinstance(limit, int) and len(state.items) < limit:
136
+ return None
137
+ return NextPage(params={self.offset_param: next_offset})
138
+
139
+
140
+ @dataclass(frozen=True, slots=True)
141
+ class PageNumberPagination:
142
+ """``?page=N`` paging, counting from ``start``."""
143
+
144
+ items: str | None = "data"
145
+ page_param: str = "page"
146
+ total_pages: str | None = None
147
+ has_more: str | None = None
148
+ start: int = 1
149
+
150
+ def next_cursor(self, state: PageState) -> str | None:
151
+ return None
152
+
153
+ def next_page(self, state: PageState) -> NextPage | None:
154
+ if not _more(state, self.has_more):
155
+ return None
156
+ page = int(cast(Any, state.params.get(self.page_param)) or self.start)
157
+ total_pages = dig(state.body, self.total_pages) if self.total_pages else None
158
+ if isinstance(total_pages, int) and page + 1 - self.start >= total_pages:
159
+ return None
160
+ return NextPage(params={self.page_param: page + 1})
161
+
162
+
163
+ _LINK_RE = re.compile(r"<([^>]*)>\s*((?:;\s*[^;,]+)*)")
164
+ _REL_NEXT_RE = re.compile(r'rel\s*=\s*"?([^";]*\s)?next(\s[^";]*)?"?')
165
+
166
+
167
+ @dataclass(frozen=True, slots=True)
168
+ class LinkHeaderPagination:
169
+ """RFC 8288 ``Link: <...>; rel="next"`` paging (GitHub style)."""
170
+
171
+ items: str | None = None
172
+
173
+ def next_cursor(self, state: PageState) -> str | None:
174
+ link = state.headers.get("link")
175
+ if not link:
176
+ return None
177
+ for url, params in _LINK_RE.findall(link):
178
+ if _REL_NEXT_RE.search(params):
179
+ return str(url)
180
+ return None
181
+
182
+ def next_page(self, state: PageState) -> NextPage | None:
183
+ url = self.next_cursor(state)
184
+ return NextPage(url=url) if url and state.items else None
185
+
186
+
187
+ class _BasePage[T]:
188
+ def __init__(
189
+ self,
190
+ *,
191
+ data: list[T],
192
+ response: httpx2.Response,
193
+ state: PageState,
194
+ strategy: PaginationStrategy,
195
+ ) -> None:
196
+ self.data = data
197
+ self.response = response
198
+ self._state = state
199
+ self._strategy = strategy
200
+
201
+ @property
202
+ def next_cursor(self) -> str | None:
203
+ """The cursor (or next URL) for the following page, if any."""
204
+ return self._strategy.next_cursor(self._state)
205
+
206
+ def has_next_page(self) -> bool:
207
+ return self._strategy.next_page(self._state) is not None
208
+
209
+ def _next(self) -> NextPage:
210
+ next_page = self._strategy.next_page(self._state)
211
+ if next_page is None:
212
+ raise RuntimeError("No next page; check has_next_page() first.")
213
+ return next_page
214
+
215
+ def __repr__(self) -> str:
216
+ return f"{type(self).__name__}(data={self.data!r})"
217
+
218
+
219
+ class Page[T](_BasePage[T]):
220
+ """One page of results; iterating it walks every item on every later page."""
221
+
222
+ def __init__(
223
+ self,
224
+ *,
225
+ data: list[T],
226
+ response: httpx2.Response,
227
+ state: PageState,
228
+ strategy: PaginationStrategy,
229
+ fetch: Callable[[NextPage], Page[T]],
230
+ ) -> None:
231
+ super().__init__(data=data, response=response, state=state, strategy=strategy)
232
+ self._fetch = fetch
233
+
234
+ def get_next_page(self) -> Page[T]:
235
+ return self._fetch(self._next())
236
+
237
+ def iter_pages(self) -> Iterator[Page[T]]:
238
+ page = self
239
+ yield page
240
+ while page.has_next_page():
241
+ page = page.get_next_page()
242
+ yield page
243
+
244
+ def __iter__(self) -> Iterator[T]:
245
+ for page in self.iter_pages():
246
+ yield from page.data
247
+
248
+
249
+ class AsyncPage[T](_BasePage[T]):
250
+ """One page of results; ``async for`` walks every item on every later page."""
251
+
252
+ def __init__(
253
+ self,
254
+ *,
255
+ data: list[T],
256
+ response: httpx2.Response,
257
+ state: PageState,
258
+ strategy: PaginationStrategy,
259
+ fetch: Callable[[NextPage], Awaitable[AsyncPage[T]]],
260
+ ) -> None:
261
+ super().__init__(data=data, response=response, state=state, strategy=strategy)
262
+ self._fetch = fetch
263
+
264
+ async def get_next_page(self) -> AsyncPage[T]:
265
+ return await self._fetch(self._next())
266
+
267
+ async def iter_pages(self) -> AsyncIterator[AsyncPage[T]]:
268
+ page = self
269
+ yield page
270
+ while page.has_next_page():
271
+ page = await page.get_next_page()
272
+ yield page
273
+
274
+ async def __aiter__(self) -> AsyncIterator[T]:
275
+ async for page in self.iter_pages():
276
+ for item in page.data:
277
+ yield item
278
+
279
+
280
+ class AsyncPaginator[T]:
281
+ """Returned by async list methods: ``await`` it for the first page, or ``async for``
282
+ over it for every item."""
283
+
284
+ def __init__(self, fetch_first: Callable[[], Awaitable[AsyncPage[T]]]) -> None:
285
+ self._fetch_first = fetch_first
286
+
287
+ def __await__(self) -> Generator[Any, None, AsyncPage[T]]:
288
+ return self._fetch_first().__await__()
289
+
290
+ async def __aiter__(self) -> AsyncIterator[T]:
291
+ page = await self._fetch_first()
292
+ async for item in page:
293
+ yield item
spec2py_runtime/_qs.py ADDED
@@ -0,0 +1,92 @@
1
+ """Serialize path and query parameters following OpenAPI ``style``/``explode`` rules."""
2
+
3
+ import enum
4
+ import urllib.parse
5
+ from collections.abc import Mapping, Sequence
6
+ from datetime import date, datetime, time
7
+ from typing import Literal, cast
8
+
9
+ import pydantic
10
+
11
+ from ._types import NotGiven
12
+
13
+ __all__ = ["QueryStyle", "encode_query", "path_template", "query_param"]
14
+
15
+ type QueryStyle = Literal["form", "spaceDelimited", "pipeDelimited", "deepObject"]
16
+ type QueryItems = list[tuple[str, str]]
17
+
18
+
19
+ def _scalar(value: object) -> str:
20
+ match value:
21
+ case bool():
22
+ return "true" if value else "false"
23
+ case None:
24
+ return ""
25
+ case enum.Enum():
26
+ return _scalar(value.value)
27
+ case datetime() | date() | time():
28
+ return value.isoformat()
29
+ case _:
30
+ return str(value)
31
+
32
+
33
+ def _as_mapping(value: object) -> Mapping[str, object] | None:
34
+ if isinstance(value, pydantic.BaseModel):
35
+ return cast(dict[str, object], value.model_dump(mode="json", by_alias=True))
36
+ if isinstance(value, Mapping):
37
+ return cast(Mapping[str, object], value)
38
+ return None
39
+
40
+
41
+ def query_param(
42
+ name: str,
43
+ value: object,
44
+ *,
45
+ style: QueryStyle = "form",
46
+ explode: bool = True,
47
+ ) -> QueryItems:
48
+ """Encode one query parameter into ``(key, value)`` pairs."""
49
+ if isinstance(value, NotGiven):
50
+ return []
51
+ if (mapping := _as_mapping(value)) is not None:
52
+ if style == "deepObject":
53
+ return [(f"{name}[{k}]", _scalar(v)) for k, v in mapping.items()]
54
+ if explode:
55
+ return [(k, _scalar(v)) for k, v in mapping.items()]
56
+ flat = ",".join(f"{k},{_scalar(v)}" for k, v in mapping.items())
57
+ return [(name, flat)]
58
+ if isinstance(value, Sequence) and not isinstance(value, str | bytes):
59
+ items = [_scalar(v) for v in cast(Sequence[object], value)]
60
+ if explode and style == "form":
61
+ return [(name, v) for v in items]
62
+ sep = {"spaceDelimited": " ", "pipeDelimited": "|"}.get(style, ",")
63
+ return [(name, sep.join(items))]
64
+ return [(name, _scalar(value))]
65
+
66
+
67
+ def encode_query(
68
+ params: Mapping[str, object],
69
+ styles: Mapping[str, tuple[QueryStyle, bool]] | None = None,
70
+ ) -> QueryItems:
71
+ """Encode a mapping of query parameters, skipping ``NOT_GIVEN`` values.
72
+
73
+ ``styles`` maps a parameter name to its ``(style, explode)`` when it isn't the
74
+ OpenAPI default of ``("form", True)``.
75
+ """
76
+ items: QueryItems = []
77
+ for name, value in params.items():
78
+ style, explode = (styles or {}).get(name, ("form", True))
79
+ items.extend(query_param(name, value, style=style, explode=explode))
80
+ return items
81
+
82
+
83
+ def path_template(template: str, /, **values: object) -> str:
84
+ """Fill ``{name}`` placeholders in a path, percent-encoding each value."""
85
+ out = template
86
+ for name, value in values.items():
87
+ if isinstance(value, Sequence) and not isinstance(value, str | bytes):
88
+ text = ",".join(_scalar(v) for v in cast(Sequence[object], value))
89
+ else:
90
+ text = _scalar(value)
91
+ out = out.replace("{" + name + "}", urllib.parse.quote(text, safe=""))
92
+ return out
@@ -0,0 +1,98 @@
1
+ """Raw responses: status, headers and the undecoded body, alongside the typed parse.
2
+
3
+ ::
4
+
5
+ raw = client.with_raw_response.invoices.retrieve("inv_1")
6
+ raw.status_code, raw.headers["x-request-id"]
7
+ invoice = raw.parse()
8
+ """
9
+
10
+ import contextvars
11
+ import functools
12
+ import json
13
+ from collections.abc import Awaitable, Callable
14
+ from typing import Any, Final, cast
15
+
16
+ import httpx2
17
+
18
+ __all__ = [
19
+ "APIResponse",
20
+ "async_to_raw_response_wrapper",
21
+ "raw_response_requested",
22
+ "to_raw_response_wrapper",
23
+ ]
24
+
25
+ _RAW_RESPONSE: Final = contextvars.ContextVar("spec2py_raw_response", default=False)
26
+
27
+
28
+ def raw_response_requested() -> bool:
29
+ return _RAW_RESPONSE.get()
30
+
31
+
32
+ class APIResponse[T]:
33
+ """An HTTP response plus a lazy, typed ``parse()``."""
34
+
35
+ def __init__(self, http_response: httpx2.Response, parse: Callable[[], T]) -> None:
36
+ self.http_response = http_response
37
+ self._parse = parse
38
+ self._parsed: list[T] = []
39
+
40
+ @property
41
+ def status_code(self) -> int:
42
+ return self.http_response.status_code
43
+
44
+ @property
45
+ def headers(self) -> httpx2.Headers:
46
+ return self.http_response.headers
47
+
48
+ @property
49
+ def content(self) -> bytes:
50
+ return self.http_response.content
51
+
52
+ @property
53
+ def text(self) -> str:
54
+ return self.http_response.text
55
+
56
+ def json(self) -> Any:
57
+ return json.loads(self.http_response.content)
58
+
59
+ def parse(self) -> T:
60
+ """Parse the body into the operation's declared return type (cached)."""
61
+ if not self._parsed:
62
+ self._parsed.append(self._parse())
63
+ return self._parsed[0]
64
+
65
+ def __repr__(self) -> str:
66
+ return f"<APIResponse [{self.status_code}] {self.http_response.url}>"
67
+
68
+
69
+ def to_raw_response_wrapper[**P, R](
70
+ func: Callable[P, R],
71
+ ) -> Callable[P, APIResponse[R]]:
72
+ """Wrap a sync resource method so it returns :class:`APIResponse` instead."""
73
+
74
+ @functools.wraps(func)
75
+ def wrapped(*args: P.args, **kwargs: P.kwargs) -> APIResponse[R]:
76
+ token = _RAW_RESPONSE.set(True)
77
+ try:
78
+ return cast(APIResponse[R], func(*args, **kwargs))
79
+ finally:
80
+ _RAW_RESPONSE.reset(token)
81
+
82
+ return wrapped
83
+
84
+
85
+ def async_to_raw_response_wrapper[**P, R](
86
+ func: Callable[P, Awaitable[R]],
87
+ ) -> Callable[P, Awaitable[APIResponse[R]]]:
88
+ """Wrap an async resource method so it returns :class:`APIResponse` instead."""
89
+
90
+ @functools.wraps(func)
91
+ async def wrapped(*args: P.args, **kwargs: P.kwargs) -> APIResponse[R]:
92
+ token = _RAW_RESPONSE.set(True)
93
+ try:
94
+ return cast(APIResponse[R], await func(*args, **kwargs))
95
+ finally:
96
+ _RAW_RESPONSE.reset(token)
97
+
98
+ return wrapped
@@ -0,0 +1,77 @@
1
+ """Retry policy: which failures to retry, and how long to wait between attempts."""
2
+
3
+ import contextlib
4
+ import email.utils
5
+ import random
6
+ import time
7
+ from dataclasses import dataclass
8
+ from typing import Final
9
+
10
+ import httpx2
11
+
12
+ __all__ = ["IDEMPOTENT_METHODS", "RetryPolicy"]
13
+
14
+ IDEMPOTENT_METHODS: Final = frozenset(
15
+ {"GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", "QUERY"}
16
+ )
17
+ _RETRY_STATUSES: Final = frozenset({408, 409, 429, 500, 502, 503, 504})
18
+
19
+
20
+ @dataclass(frozen=True, slots=True)
21
+ class RetryPolicy:
22
+ """Exponential backoff with jitter that honours ``Retry-After``.
23
+
24
+ Requests are retried only when they are safe to repeat: idempotent methods,
25
+ or any method carrying an idempotency key. A server may force the decision
26
+ either way with an ``x-should-retry: true|false`` header.
27
+ """
28
+
29
+ max_retries: int = 2
30
+ initial_delay: float = 0.5
31
+ max_delay: float = 8.0
32
+ jitter: float = 0.25
33
+ max_retry_after: float = 60.0
34
+ retry_statuses: frozenset[int] = _RETRY_STATUSES
35
+
36
+ def can_retry(
37
+ self, request: httpx2.Request, idempotency_header: str | None
38
+ ) -> bool:
39
+ if request.method.upper() in IDEMPOTENT_METHODS:
40
+ return True
41
+ return bool(idempotency_header and idempotency_header in request.headers)
42
+
43
+ def should_retry_response(self, response: httpx2.Response) -> bool:
44
+ match response.headers.get("x-should-retry", "").lower():
45
+ case "true":
46
+ return True
47
+ case "false":
48
+ return False
49
+ case _:
50
+ return response.status_code in self.retry_statuses
51
+
52
+ def delay(self, attempt: int, response: httpx2.Response | None = None) -> float:
53
+ """Seconds to sleep before retry number ``attempt`` (0-based)."""
54
+ if response is not None and (hinted := self._retry_after(response)) is not None:
55
+ return hinted
56
+ backoff = min(self.initial_delay * 2.0**attempt, self.max_delay)
57
+ return backoff * (1 - self.jitter * random.random())
58
+
59
+ def _retry_after(self, response: httpx2.Response) -> float | None:
60
+ headers = response.headers
61
+ seconds: float | None = None
62
+ if (ms := headers.get("retry-after-ms")) is not None:
63
+ with contextlib.suppress(ValueError):
64
+ seconds = float(ms) / 1000
65
+ if seconds is None and (value := headers.get("retry-after")) is not None:
66
+ try:
67
+ seconds = float(value)
68
+ except ValueError:
69
+ try:
70
+ parsed = email.utils.parsedate_to_datetime(value)
71
+ except TypeError, ValueError:
72
+ parsed = None
73
+ if parsed is not None:
74
+ seconds = max(parsed.timestamp() - time.time(), 0.0)
75
+ if seconds is None or not 0 <= seconds <= self.max_retry_after:
76
+ return None
77
+ return seconds