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/__init__.py +132 -0
- lexapi/_base.py +122 -0
- lexapi/_meta.py +14 -0
- lexapi/_payloads.py +160 -0
- lexapi/_response.py +158 -0
- lexapi/_retry.py +148 -0
- lexapi/async_client.py +417 -0
- lexapi/citations.py +231 -0
- lexapi/client.py +491 -0
- lexapi/errors.py +261 -0
- lexapi/export.py +253 -0
- lexapi/models.py +1253 -0
- lexapi/py.typed +0 -0
- lexapi/webhooks.py +220 -0
- lexapi_client-0.1.0.dist-info/METADATA +310 -0
- lexapi_client-0.1.0.dist-info/RECORD +17 -0
- lexapi_client-0.1.0.dist-info/WHEEL +4 -0
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()
|