lexapi-client 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.
lexapi/_retry.py ADDED
@@ -0,0 +1,148 @@
1
+ """Retry policy: what to retry, and how long to wait.
2
+
3
+ Defaults (SDK contract §1.2):
4
+
5
+ - up to 3 retries with exponential backoff + full jitter (base 0.5 s, cap 30 s)
6
+ - retryable statuses: 429, 502, 503, 504 — plus connect-phase transport
7
+ errors (the request never reached the server, so any method is safe)
8
+ - non-idempotent methods (POST/PUT/PATCH/DELETE) retry **only** on 429
9
+ (and connect-phase errors); GET retries on every retryable status
10
+ - server-directed wait wins over computed backoff. Resolution order:
11
+
12
+ 1. ``Retry-After`` response header (seconds or HTTP-date),
13
+ 2. ``RateLimit-Reset`` / ``X-RateLimit-Reset`` header (delta-seconds),
14
+ 3. the JSON ``retryAfter`` body field — **last resort only**: a known
15
+ server bug emitted epoch seconds instead of delta seconds here, so
16
+ epoch-looking values are converted to a delta defensively,
17
+ 4. computed exponential backoff.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import email.utils
23
+ import random
24
+ import time
25
+ from dataclasses import dataclass, field
26
+ from typing import Any
27
+
28
+ import httpx
29
+
30
+ #: JSON ``retryAfter`` values above this are assumed to be (buggy) epoch
31
+ #: seconds rather than delta seconds and are converted to a delta.
32
+ _EPOCH_THRESHOLD = 10_000_000
33
+
34
+ _IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class RetryConfig:
39
+ """Retry policy knobs. ``max_retries=0`` disables retries entirely."""
40
+
41
+ max_retries: int = 3
42
+ backoff_base: float = 0.5
43
+ backoff_cap: float = 30.0
44
+ retry_statuses: frozenset = field(default_factory=lambda: frozenset({429, 502, 503, 504}))
45
+ #: Statuses retried even for non-idempotent methods.
46
+ retry_statuses_non_idempotent: frozenset = field(default_factory=lambda: frozenset({429}))
47
+
48
+
49
+ DEFAULT_RETRY_CONFIG = RetryConfig()
50
+
51
+
52
+ def compute_backoff(attempt: int, config: RetryConfig) -> float:
53
+ """Exponential backoff with full jitter: ``U(0, min(cap, base * 2**attempt))``."""
54
+ ceiling = min(config.backoff_cap, config.backoff_base * (2**attempt))
55
+ return random.uniform(0, ceiling)
56
+
57
+
58
+ def parse_retry_after(value: str) -> float | None:
59
+ """Parse a ``Retry-After`` header: delta-seconds or HTTP-date."""
60
+ value = value.strip()
61
+ try:
62
+ seconds = float(value)
63
+ except ValueError:
64
+ try:
65
+ when = email.utils.parsedate_to_datetime(value)
66
+ except (TypeError, ValueError):
67
+ return None
68
+ if when is None:
69
+ return None
70
+ return max(0.0, when.timestamp() - time.time())
71
+ return seconds if seconds >= 0 else None
72
+
73
+
74
+ def _body_retry_after(body: Any) -> float | None:
75
+ """JSON ``retryAfter`` field, defensively handling the epoch-seconds bug."""
76
+ if not isinstance(body, dict):
77
+ return None
78
+ raw = body.get("retryAfter")
79
+ if isinstance(raw, bool) or not isinstance(raw, (int, float)):
80
+ return None
81
+ value = float(raw)
82
+ if value < 0:
83
+ return None
84
+ if value > _EPOCH_THRESHOLD: # buggy epoch-seconds shape → convert to delta
85
+ return max(0.0, value - time.time())
86
+ return value
87
+
88
+
89
+ def server_wait_hint(headers: httpx.Headers, body: Any) -> float | None:
90
+ """Resolve the server-directed wait for a 429/5xx response, if any.
91
+
92
+ Header sources are preferred over the JSON ``retryAfter`` body field
93
+ (which was buggy — epoch seconds — until a pending server fix).
94
+ """
95
+ header = headers.get("retry-after")
96
+ if header is not None:
97
+ parsed = parse_retry_after(header)
98
+ if parsed is not None:
99
+ return parsed
100
+ for name in ("ratelimit-reset", "x-ratelimit-reset"):
101
+ reset = headers.get(name)
102
+ if reset is not None:
103
+ try:
104
+ seconds = float(reset)
105
+ except ValueError:
106
+ continue
107
+ if seconds > _EPOCH_THRESHOLD: # some servers emit epoch here too
108
+ seconds = seconds - time.time()
109
+ if seconds >= 0:
110
+ return seconds
111
+ return _body_retry_after(body)
112
+
113
+
114
+ def is_retryable_exception(exc: httpx.HTTPError) -> bool:
115
+ """Connect-phase failures are safe to retry for any method.
116
+
117
+ The request never reached the server (connection or connect-timeout
118
+ failure), so retrying cannot duplicate a side effect.
119
+ """
120
+ return isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout))
121
+
122
+
123
+ def is_retryable_status(method: str, status: int, config: RetryConfig) -> bool:
124
+ if method.upper() in _IDEMPOTENT_METHODS:
125
+ return status in config.retry_statuses
126
+ return status in config.retry_statuses_non_idempotent
127
+
128
+
129
+ def retry_wait(
130
+ method: str,
131
+ response: httpx.Response,
132
+ body: Any,
133
+ attempt: int,
134
+ config: RetryConfig,
135
+ ) -> float | None:
136
+ """Seconds to sleep before retry *attempt*, or ``None`` for "don't retry".
137
+
138
+ Server-directed waits win over computed backoff but are clamped to
139
+ ``backoff_cap`` so a pathological ``Retry-After`` can't stall the caller.
140
+ """
141
+ if attempt >= config.max_retries:
142
+ return None
143
+ if not is_retryable_status(method, response.status_code, config):
144
+ return None
145
+ hint = server_wait_hint(response.headers, body)
146
+ if hint is not None:
147
+ return min(hint, config.backoff_cap)
148
+ return compute_backoff(attempt, config)
lexapi/async_client.py ADDED
@@ -0,0 +1,417 @@
1
+ """Asynchronous LexAPI client (mirrors :class:`lexapi.LexAPI`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from typing import Any, TypeVar
7
+
8
+ import httpx
9
+
10
+ from lexapi import _payloads
11
+ from lexapi._base import (
12
+ DEFAULT_BASE_URL,
13
+ build_httpx_kwargs,
14
+ exception_retry_wait,
15
+ make_retry_config,
16
+ process_response,
17
+ status_retry_wait,
18
+ transport_error,
19
+ )
20
+ from lexapi._response import APIResponse
21
+ from lexapi._retry import RetryConfig
22
+ from lexapi.citations import AsyncCitationsResource
23
+ from lexapi.export import AsyncExportStream, export_params
24
+ from lexapi.models import (
25
+ DocumentBatchResponse,
26
+ DocumentByUrlResponse,
27
+ DocumentMetadataResponse,
28
+ DocumentResponse,
29
+ DocumentVersionResponse,
30
+ DocumentVersionsResponse,
31
+ RecentDocumentsResponse,
32
+ ResolveResponse,
33
+ SearchResponse,
34
+ SemanticLegislationResponse,
35
+ SemanticSearchResponse,
36
+ )
37
+ from lexapi.webhooks import AsyncWebhooksResource
38
+
39
+ R = TypeVar("R", bound=APIResponse)
40
+
41
+
42
+ class AsyncLexAPI:
43
+ """Asynchronous LexAPI client.
44
+
45
+ Same configuration surface as :class:`lexapi.LexAPI`; every operation
46
+ method is a coroutine. Shares all request-building, retry, and
47
+ response-parsing logic with the sync client.
48
+ """
49
+
50
+ def __init__(
51
+ self,
52
+ api_key: str | None = None,
53
+ *,
54
+ base_url: str = DEFAULT_BASE_URL,
55
+ timeout: float | httpx.Timeout = 60.0,
56
+ connect_timeout: float = 10.0,
57
+ max_retries: int | None = None,
58
+ retry_config: RetryConfig | None = None,
59
+ user_agent_suffix: str | None = None,
60
+ transport: httpx.AsyncBaseTransport | None = None,
61
+ ) -> None:
62
+ self._retry = make_retry_config(max_retries, retry_config)
63
+ self._http = httpx.AsyncClient(
64
+ transport=transport,
65
+ **build_httpx_kwargs(
66
+ api_key, base_url, timeout, connect_timeout, user_agent_suffix
67
+ ),
68
+ )
69
+ #: Citation-graph operations (``client.citations.cited_by(...)``, ...).
70
+ self.citations = AsyncCitationsResource(self)
71
+ #: Webhook subscriptions (``client.webhooks.create(...)``, ...).
72
+ self.webhooks = AsyncWebhooksResource(self)
73
+
74
+ # ── Meta ──────────────────────────────────────────────────────────
75
+ async def get_info(self) -> APIResponse:
76
+ """GET /info — API capabilities, subscription tier, and current usage.
77
+
78
+ Free operation (0 credits).
79
+ """
80
+ return await self._request("GET", "/info")
81
+
82
+ # ── Search ────────────────────────────────────────────────────────
83
+ async def search(
84
+ self,
85
+ query: str | None = None,
86
+ *,
87
+ text_scope: str | None = None,
88
+ date_from: str | None = None,
89
+ date_to: str | None = None,
90
+ year: int | list[int] | None = None,
91
+ month: int | list[int] | None = None,
92
+ document_type: str | list[str] | None = None,
93
+ author: str | list[str] | None = None,
94
+ procedure: str | list[str] | None = None,
95
+ domain: str | None = None,
96
+ subdomain: str | list[str] | None = None,
97
+ language: str | None = None,
98
+ max_pages: int | None = None,
99
+ ) -> SearchResponse:
100
+ """POST /search — see :meth:`lexapi.LexAPI.search`."""
101
+ body = _payloads.search_body(
102
+ query,
103
+ text_scope=text_scope,
104
+ date_from=date_from,
105
+ date_to=date_to,
106
+ year=year,
107
+ month=month,
108
+ document_type=document_type,
109
+ author=author,
110
+ procedure=procedure,
111
+ domain=domain,
112
+ subdomain=subdomain,
113
+ language=language,
114
+ max_pages=max_pages,
115
+ )
116
+ return await self._request("POST", "/search", json=body, cast=SearchResponse)
117
+
118
+ # ── Documents ─────────────────────────────────────────────────────
119
+ async def get_document(
120
+ self,
121
+ celex: str,
122
+ *,
123
+ bypass_corpus: bool | None = None,
124
+ language: str | None = None,
125
+ include: str | list[str] | None = None,
126
+ fields: str | list[str] | None = None,
127
+ article_id: str | None = None,
128
+ ) -> DocumentResponse:
129
+ """POST /documentContent — see :meth:`lexapi.LexAPI.get_document`."""
130
+ body = _payloads.document_content_body(
131
+ celex,
132
+ bypass_corpus=bypass_corpus,
133
+ language=language,
134
+ include=include,
135
+ fields=fields,
136
+ article_id=article_id,
137
+ )
138
+ return await self._request(
139
+ "POST", "/documentContent", json=body, cast=DocumentResponse
140
+ )
141
+
142
+ async def get_documents_batch(
143
+ self,
144
+ celexes: list[str],
145
+ *,
146
+ bypass_corpus: bool | None = None,
147
+ language: str | None = None,
148
+ include: str | list[str] | None = None,
149
+ fields: str | list[str] | None = None,
150
+ article_id: str | None = None,
151
+ ) -> DocumentBatchResponse:
152
+ """POST /documentContent/batch — see :meth:`lexapi.LexAPI.get_documents_batch`."""
153
+ body = _payloads.document_batch_body(
154
+ celexes,
155
+ bypass_corpus=bypass_corpus,
156
+ language=language,
157
+ include=include,
158
+ fields=fields,
159
+ article_id=article_id,
160
+ )
161
+ return await self._request(
162
+ "POST", "/documentContent/batch", json=body, cast=DocumentBatchResponse
163
+ )
164
+
165
+ async def get_recent_documents(
166
+ self,
167
+ *,
168
+ days: int | None = None,
169
+ document_type: str | None = None,
170
+ author: str | None = None,
171
+ domain: str | None = None,
172
+ subdomain: str | None = None,
173
+ language: str | None = None,
174
+ limit: int | None = None,
175
+ ) -> RecentDocumentsResponse:
176
+ """GET /documents/recent — see :meth:`lexapi.LexAPI.get_recent_documents`."""
177
+ params = _payloads.recent_documents_params(
178
+ days=days,
179
+ document_type=document_type,
180
+ author=author,
181
+ domain=domain,
182
+ subdomain=subdomain,
183
+ language=language,
184
+ limit=limit,
185
+ )
186
+ return await self._request(
187
+ "GET", "/documents/recent", params=params, cast=RecentDocumentsResponse
188
+ )
189
+
190
+ async def get_document_by_url(
191
+ self,
192
+ url: str,
193
+ *,
194
+ include: str | list[str] | None = None,
195
+ fields: str | list[str] | None = None,
196
+ article_id: str | None = None,
197
+ ) -> DocumentByUrlResponse:
198
+ """POST /documents/url — see :meth:`lexapi.LexAPI.get_document_by_url`."""
199
+ body = _payloads.document_by_url_body(
200
+ url, include=include, fields=fields, article_id=article_id
201
+ )
202
+ return await self._request(
203
+ "POST", "/documents/url", json=body, cast=DocumentByUrlResponse
204
+ )
205
+
206
+ async def get_document_metadata(
207
+ self, celex: str, *, bypass_corpus: bool | None = None
208
+ ) -> DocumentMetadataResponse:
209
+ """POST /documents/metadata — see :meth:`lexapi.LexAPI.get_document_metadata`."""
210
+ body = _payloads.drop_none({"celexNumber": celex, "bypassCorpus": bypass_corpus})
211
+ return await self._request(
212
+ "POST", "/documents/metadata", json=body, cast=DocumentMetadataResponse
213
+ )
214
+
215
+ async def resolve(self, identifier: str) -> ResolveResponse:
216
+ """POST /resolve — see :meth:`lexapi.LexAPI.resolve`."""
217
+ return await self._request(
218
+ "POST", "/resolve", json={"identifier": identifier}, cast=ResolveResponse
219
+ )
220
+
221
+ # ── Point-in-time versions ────────────────────────────────────────
222
+ async def list_document_versions(
223
+ self, celex: str, *, language: str | None = None
224
+ ) -> DocumentVersionsResponse:
225
+ """GET /documents/{celex}/versions — see :meth:`lexapi.LexAPI.list_document_versions`."""
226
+ params = _payloads.drop_none({"language": language})
227
+ return await self._request(
228
+ "GET",
229
+ f"/documents/{celex}/versions",
230
+ params=params,
231
+ cast=DocumentVersionsResponse,
232
+ )
233
+
234
+ async def get_document_version(
235
+ self, celex: str, version: int, *, language: str | None = None
236
+ ) -> DocumentVersionResponse:
237
+ """GET /documents/{celex}/versions/{version} — see
238
+ :meth:`lexapi.LexAPI.get_document_version`."""
239
+ params = _payloads.drop_none({"language": language})
240
+ return await self._request(
241
+ "GET",
242
+ f"/documents/{celex}/versions/{version}",
243
+ params=params,
244
+ cast=DocumentVersionResponse,
245
+ )
246
+
247
+ async def get_document_at_date(
248
+ self, celex: str, date: str, *, language: str | None = None
249
+ ) -> DocumentVersionResponse:
250
+ """GET /documents/{celex}/at/{date} — see :meth:`lexapi.LexAPI.get_document_at_date`."""
251
+ params = _payloads.drop_none({"language": language})
252
+ return await self._request(
253
+ "GET",
254
+ f"/documents/{celex}/at/{date}",
255
+ params=params,
256
+ cast=DocumentVersionResponse,
257
+ )
258
+
259
+ # ── Semantic search ───────────────────────────────────────────────
260
+ async def semantic_search(
261
+ self,
262
+ query: str,
263
+ *,
264
+ hyde: bool = False,
265
+ min_score: float | None = None,
266
+ limit: int | None = None,
267
+ language: str | None = None,
268
+ include_text: bool = False,
269
+ filters: dict | None = None,
270
+ ) -> SemanticSearchResponse:
271
+ """POST /search/semantic — see :meth:`lexapi.LexAPI.semantic_search`.
272
+
273
+ ``hyde=True`` bills **15 credits instead of 5** (~1-3 s extra latency);
274
+ best-effort — on LLM failure the response reports ``hyde=False`` and
275
+ the 10-credit premium is refunded automatically.
276
+ """
277
+ body = _payloads.semantic_search_body(
278
+ query,
279
+ hyde=hyde,
280
+ min_score=min_score,
281
+ limit=limit,
282
+ language=language,
283
+ include_text=include_text,
284
+ filters=filters,
285
+ )
286
+ return await self._request(
287
+ "POST", "/search/semantic", json=body, cast=SemanticSearchResponse
288
+ )
289
+
290
+ async def semantic_legislation_search(
291
+ self,
292
+ query: str,
293
+ *,
294
+ min_score: float | None = None,
295
+ limit: int | None = None,
296
+ language: str | None = None,
297
+ include_text: bool = False,
298
+ filters: dict | None = None,
299
+ ) -> SemanticLegislationResponse:
300
+ """POST /legislation/semantic — see
301
+ :meth:`lexapi.LexAPI.semantic_legislation_search`.
302
+ """
303
+ body = _payloads.semantic_search_body(
304
+ query,
305
+ min_score=min_score,
306
+ limit=limit,
307
+ language=language,
308
+ include_text=include_text,
309
+ filters=filters,
310
+ )
311
+ return await self._request(
312
+ "POST", "/legislation/semantic", json=body, cast=SemanticLegislationResponse
313
+ )
314
+
315
+ # ── Export ────────────────────────────────────────────────────────
316
+ async def export(
317
+ self,
318
+ *,
319
+ document_type: str | list[str] | None = None,
320
+ author: str | list[str] | None = None,
321
+ subdomain: str | list[str] | None = None,
322
+ language: str | None = None,
323
+ date_from: str | None = None,
324
+ date_to: str | None = None,
325
+ fetched_since: str | None = None,
326
+ include_html: bool | None = None,
327
+ include_content: bool | None = None,
328
+ limit: int | None = None,
329
+ ) -> AsyncExportStream:
330
+ """GET /export — see :meth:`lexapi.LexAPI.export`. Returns an
331
+ :class:`~lexapi.export.AsyncExportStream`::
332
+
333
+ async with await client.export(limit=1000) as stream:
334
+ async for row in stream:
335
+ handle(row)
336
+ """
337
+ params = export_params(
338
+ document_type=document_type,
339
+ author=author,
340
+ subdomain=subdomain,
341
+ language=language,
342
+ date_from=date_from,
343
+ date_to=date_to,
344
+ fetched_since=fetched_since,
345
+ include_html=include_html,
346
+ include_content=include_content,
347
+ limit=limit,
348
+ )
349
+ return AsyncExportStream(
350
+ await self._stream_request("GET", "/export", params=params)
351
+ )
352
+
353
+ async def _stream_request(
354
+ self, method: str, path: str, *, params: dict[str, Any] | None = None
355
+ ) -> httpx.Response:
356
+ """Streaming twin of :meth:`_request`; body left unread on success."""
357
+ attempt = 0
358
+ while True:
359
+ request = self._http.build_request(method, path, params=params)
360
+ try:
361
+ response = await self._http.send(request, stream=True)
362
+ except httpx.HTTPError as exc:
363
+ wait = exception_retry_wait(exc, attempt, self._retry)
364
+ if wait is None:
365
+ raise transport_error(exc) from exc
366
+ await asyncio.sleep(wait)
367
+ attempt += 1
368
+ continue
369
+ if response.is_success:
370
+ return response
371
+ await response.aread()
372
+ wait = status_retry_wait(method, response, attempt, self._retry)
373
+ if wait is None:
374
+ process_response(response) # raises the typed error
375
+ await response.aclose()
376
+ await asyncio.sleep(wait)
377
+ attempt += 1
378
+
379
+ # ── Request core ──────────────────────────────────────────────────
380
+ async def _request(
381
+ self,
382
+ method: str,
383
+ path: str,
384
+ *,
385
+ params: dict[str, Any] | None = None,
386
+ json: Any | None = None,
387
+ cast: type[R] = APIResponse, # type: ignore[assignment]
388
+ timeout: float | httpx.Timeout | None = None,
389
+ ) -> R:
390
+ request_kwargs: dict[str, Any] = {"params": params, "json": json}
391
+ if timeout is not None:
392
+ request_kwargs["timeout"] = timeout
393
+ attempt = 0
394
+ while True:
395
+ try:
396
+ response = await self._http.request(method, path, **request_kwargs)
397
+ except httpx.HTTPError as exc:
398
+ wait = exception_retry_wait(exc, attempt, self._retry)
399
+ if wait is None:
400
+ raise transport_error(exc) from exc
401
+ await asyncio.sleep(wait)
402
+ attempt += 1
403
+ continue
404
+ wait = status_retry_wait(method, response, attempt, self._retry)
405
+ if wait is None:
406
+ return process_response(response, cast)
407
+ await asyncio.sleep(wait)
408
+ attempt += 1
409
+
410
+ async def close(self) -> None:
411
+ await self._http.aclose()
412
+
413
+ async def __aenter__(self) -> AsyncLexAPI:
414
+ return self
415
+
416
+ async def __aexit__(self, *exc: object) -> None:
417
+ await self.close()