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/client.py ADDED
@@ -0,0 +1,491 @@
1
+ """Synchronous LexAPI client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
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 CitationsResource
23
+ from lexapi.export import ExportStream, 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 WebhooksResource
38
+
39
+ R = TypeVar("R", bound=APIResponse)
40
+
41
+
42
+ class LexAPI:
43
+ """Synchronous LexAPI client.
44
+
45
+ Args:
46
+ api_key: LexAPI key (``lex_...``). Falls back to ``LEXAPI_API_KEY``.
47
+ Keys are server-side secrets — never ship them in client-side code.
48
+ base_url: API base URL (defaults to production).
49
+ timeout: read/overall timeout in seconds, or a full ``httpx.Timeout``.
50
+ connect_timeout: connect timeout in seconds (ignored when ``timeout``
51
+ is an ``httpx.Timeout``).
52
+ max_retries: retry budget for 429/502/503/504 and connect errors
53
+ (default 3). ``0`` disables retries.
54
+ retry_config: full :class:`~lexapi._retry.RetryConfig` override;
55
+ takes precedence over ``max_retries``.
56
+ user_agent_suffix: optional suffix appended to the
57
+ ``lexapi-python/<version>`` User-Agent.
58
+ transport: optional httpx transport (used for testing).
59
+ """
60
+
61
+ def __init__(
62
+ self,
63
+ api_key: str | None = None,
64
+ *,
65
+ base_url: str = DEFAULT_BASE_URL,
66
+ timeout: float | httpx.Timeout = 60.0,
67
+ connect_timeout: float = 10.0,
68
+ max_retries: int | None = None,
69
+ retry_config: RetryConfig | None = None,
70
+ user_agent_suffix: str | None = None,
71
+ transport: httpx.BaseTransport | None = None,
72
+ ) -> None:
73
+ self._retry = make_retry_config(max_retries, retry_config)
74
+ self._http = httpx.Client(
75
+ transport=transport,
76
+ **build_httpx_kwargs(
77
+ api_key, base_url, timeout, connect_timeout, user_agent_suffix
78
+ ),
79
+ )
80
+ #: Citation-graph operations (``client.citations.cited_by(...)``, ...).
81
+ self.citations = CitationsResource(self)
82
+ #: Webhook subscriptions (``client.webhooks.create(...)``, ...).
83
+ self.webhooks = WebhooksResource(self)
84
+
85
+ # ── Meta ──────────────────────────────────────────────────────────
86
+ def get_info(self) -> APIResponse:
87
+ """GET /info — API capabilities, subscription tier, and current usage.
88
+
89
+ Free operation (0 credits).
90
+ """
91
+ return self._request("GET", "/info")
92
+
93
+ # ── Search ────────────────────────────────────────────────────────
94
+ def search(
95
+ self,
96
+ query: str | None = None,
97
+ *,
98
+ text_scope: str | None = None,
99
+ date_from: str | None = None,
100
+ date_to: str | None = None,
101
+ year: int | list[int] | None = None,
102
+ month: int | list[int] | None = None,
103
+ document_type: str | list[str] | None = None,
104
+ author: str | list[str] | None = None,
105
+ procedure: str | list[str] | None = None,
106
+ domain: str | None = None,
107
+ subdomain: str | list[str] | None = None,
108
+ language: str | None = None,
109
+ max_pages: int | None = None,
110
+ ) -> SearchResponse:
111
+ """POST /search — search EUR-Lex with structured filters.
112
+
113
+ At least one filter is required by the server. ``max_pages`` is
114
+ clamped to the subscription tier; check ``response.truncated`` /
115
+ ``response.partial`` / ``response.warning`` for capping signals.
116
+ Prefer 1-3 distinctive query terms — EUR-Lex keyword matching is
117
+ literal (use semantic search for concept queries).
118
+ """
119
+ body = _payloads.search_body(
120
+ query,
121
+ text_scope=text_scope,
122
+ date_from=date_from,
123
+ date_to=date_to,
124
+ year=year,
125
+ month=month,
126
+ document_type=document_type,
127
+ author=author,
128
+ procedure=procedure,
129
+ domain=domain,
130
+ subdomain=subdomain,
131
+ language=language,
132
+ max_pages=max_pages,
133
+ )
134
+ return self._request("POST", "/search", json=body, cast=SearchResponse)
135
+
136
+ # ── Documents ─────────────────────────────────────────────────────
137
+ def get_document(
138
+ self,
139
+ celex: str,
140
+ *,
141
+ bypass_corpus: bool | None = None,
142
+ language: str | None = None,
143
+ include: str | list[str] | None = None,
144
+ fields: str | list[str] | None = None,
145
+ article_id: str | None = None,
146
+ ) -> DocumentResponse:
147
+ """POST /documentContent — fetch one fully-parsed document by CELEX.
148
+
149
+ Corpus-first read path: ``response.source`` reports ``corpus`` or
150
+ ``live``; pass ``bypass_corpus=True`` to force a live scrape.
151
+ ``include``/``fields`` trim the payload to the listed pieces
152
+ (``metadata``, ``fullText``, ``articles``, ``recitals``, ``sections``,
153
+ ``tables``, ``annexes``); ``article_id`` narrows to one article.
154
+ """
155
+ body = _payloads.document_content_body(
156
+ celex,
157
+ bypass_corpus=bypass_corpus,
158
+ language=language,
159
+ include=include,
160
+ fields=fields,
161
+ article_id=article_id,
162
+ )
163
+ return self._request("POST", "/documentContent", json=body, cast=DocumentResponse)
164
+
165
+ def get_documents_batch(
166
+ self,
167
+ celexes: list[str],
168
+ *,
169
+ bypass_corpus: bool | None = None,
170
+ language: str | None = None,
171
+ include: str | list[str] | None = None,
172
+ fields: str | list[str] | None = None,
173
+ article_id: str | None = None,
174
+ ) -> DocumentBatchResponse:
175
+ """POST /documentContent/batch — fetch multiple documents at once.
176
+
177
+ Per-CELEX failures land in ``response.errors`` instead of aborting
178
+ the batch. The batch size is clamped to the tier ceiling —
179
+ ``response.trimmed`` / ``trimmed_to`` / ``trimmed_reason`` (and the
180
+ ``X-Warning`` header via ``response.warning``) report clamping.
181
+ """
182
+ body = _payloads.document_batch_body(
183
+ celexes,
184
+ bypass_corpus=bypass_corpus,
185
+ language=language,
186
+ include=include,
187
+ fields=fields,
188
+ article_id=article_id,
189
+ )
190
+ return self._request(
191
+ "POST", "/documentContent/batch", json=body, cast=DocumentBatchResponse
192
+ )
193
+
194
+ def get_recent_documents(
195
+ self,
196
+ *,
197
+ days: int | None = None,
198
+ document_type: str | None = None,
199
+ author: str | None = None,
200
+ domain: str | None = None,
201
+ subdomain: str | None = None,
202
+ language: str | None = None,
203
+ limit: int | None = None,
204
+ ) -> RecentDocumentsResponse:
205
+ """GET /documents/recent — documents published in the last ``days`` days."""
206
+ params = _payloads.recent_documents_params(
207
+ days=days,
208
+ document_type=document_type,
209
+ author=author,
210
+ domain=domain,
211
+ subdomain=subdomain,
212
+ language=language,
213
+ limit=limit,
214
+ )
215
+ return self._request(
216
+ "GET", "/documents/recent", params=params, cast=RecentDocumentsResponse
217
+ )
218
+
219
+ def get_document_by_url(
220
+ self,
221
+ url: str,
222
+ *,
223
+ include: str | list[str] | None = None,
224
+ fields: str | list[str] | None = None,
225
+ article_id: str | None = None,
226
+ ) -> DocumentByUrlResponse:
227
+ """POST /documents/url — fetch a document by any EUR-Lex URL.
228
+
229
+ The response echoes ``source_url`` and the ``extracted_celex``.
230
+ """
231
+ body = _payloads.document_by_url_body(
232
+ url, include=include, fields=fields, article_id=article_id
233
+ )
234
+ return self._request("POST", "/documents/url", json=body, cast=DocumentByUrlResponse)
235
+
236
+ def get_document_metadata(
237
+ self, celex: str, *, bypass_corpus: bool | None = None
238
+ ) -> DocumentMetadataResponse:
239
+ """POST /documents/metadata — metadata only (faster/cheaper than content)."""
240
+ body = _payloads.drop_none({"celexNumber": celex, "bypassCorpus": bypass_corpus})
241
+ return self._request(
242
+ "POST", "/documents/metadata", json=body, cast=DocumentMetadataResponse
243
+ )
244
+
245
+ def resolve(self, identifier: str) -> ResolveResponse:
246
+ """POST /resolve — resolve a CELEX / EUR-Lex URL / ELI / ECLI to a CELEX."""
247
+ return self._request(
248
+ "POST", "/resolve", json={"identifier": identifier}, cast=ResolveResponse
249
+ )
250
+
251
+ # ── Point-in-time versions ────────────────────────────────────────
252
+ # Requires lex-api PR #72 deployed. Versions are LexAPI observation
253
+ # snapshots (content-hash changes between fetches), NOT legal in-force
254
+ # reconstructions; history begins at first ingestion.
255
+
256
+ def list_document_versions(
257
+ self, celex: str, *, language: str | None = None
258
+ ) -> DocumentVersionsResponse:
259
+ """GET /documents/{celex}/versions — version history, newest first (1 credit)."""
260
+ params = _payloads.drop_none({"language": language})
261
+ return self._request(
262
+ "GET",
263
+ f"/documents/{celex}/versions",
264
+ params=params,
265
+ cast=DocumentVersionsResponse,
266
+ )
267
+
268
+ def get_document_version(
269
+ self, celex: str, version: int, *, language: str | None = None
270
+ ) -> DocumentVersionResponse:
271
+ """GET /documents/{celex}/versions/{version} — one immutable
272
+ snapshot with content (1 credit)."""
273
+ params = _payloads.drop_none({"language": language})
274
+ return self._request(
275
+ "GET",
276
+ f"/documents/{celex}/versions/{version}",
277
+ params=params,
278
+ cast=DocumentVersionResponse,
279
+ )
280
+
281
+ def get_document_at_date(
282
+ self, celex: str, date: str, *, language: str | None = None
283
+ ) -> DocumentVersionResponse:
284
+ """GET /documents/{celex}/at/{date} — the snapshot observed as current on ``date``.
285
+
286
+ ``date`` is ``YYYY-MM-DD`` (end-of-day UTC inclusive). Dates before
287
+ the document entered the corpus raise :class:`NotFoundError` with
288
+ the tracking start date in the message. 1 credit.
289
+ """
290
+ params = _payloads.drop_none({"language": language})
291
+ return self._request(
292
+ "GET",
293
+ f"/documents/{celex}/at/{date}",
294
+ params=params,
295
+ cast=DocumentVersionResponse,
296
+ )
297
+
298
+ # ── Semantic search ───────────────────────────────────────────────
299
+ def semantic_search(
300
+ self,
301
+ query: str,
302
+ *,
303
+ hyde: bool = False,
304
+ min_score: float | None = None,
305
+ limit: int | None = None,
306
+ language: str | None = None,
307
+ include_text: bool = False,
308
+ filters: dict | None = None,
309
+ ) -> SemanticSearchResponse:
310
+ """POST /search/semantic — embedding-based CJEU case-law search.
311
+
312
+ Args:
313
+ query: natural-language query to embed.
314
+ hyde: enable HyDE query rewriting — an LLM drafts the passage a
315
+ relevant judgment would contain and retrieval fuses plain-query
316
+ and hypothetical-passage rankings. Markedly better recall on
317
+ short or keyword-style queries. **Bills 15 credits instead of
318
+ 5** and adds ~1-3 s of latency. Best-effort: on generation
319
+ failure the search falls back to plain retrieval, the response
320
+ reports ``hyde=False``, and the 10-credit premium is
321
+ **refunded automatically** (``response.units_charged`` then
322
+ reflects the base rate).
323
+ min_score: drop results below this cosine similarity. Without it
324
+ the upstream applies a ~0.7 relevance floor — if you got fewer
325
+ results than ``limit``, lower this (e.g. 0.5) to widen recall,
326
+ or pass 0 to disable the floor.
327
+ limit: max results (clamped to the tier's maxResults).
328
+ language: language of returned content (default ``en``).
329
+ include_text: receive full document text per hit instead of the
330
+ default ~600-char snippet (10-50x payload increase).
331
+ filters: free-form filter object forwarded to the backend.
332
+
333
+ The response exposes ``hint`` (low-confidence signal), ``hyde``
334
+ (whether HyDE actually ran), and ``hypothetical_document`` (the
335
+ LLM-drafted passage, when HyDE ran).
336
+ """
337
+ body = _payloads.semantic_search_body(
338
+ query,
339
+ hyde=hyde,
340
+ min_score=min_score,
341
+ limit=limit,
342
+ language=language,
343
+ include_text=include_text,
344
+ filters=filters,
345
+ )
346
+ return self._request(
347
+ "POST", "/search/semantic", json=body, cast=SemanticSearchResponse
348
+ )
349
+
350
+ def semantic_legislation_search(
351
+ self,
352
+ query: str,
353
+ *,
354
+ min_score: float | None = None,
355
+ limit: int | None = None,
356
+ language: str | None = None,
357
+ include_text: bool = False,
358
+ filters: dict | None = None,
359
+ ) -> SemanticLegislationResponse:
360
+ """POST /legislation/semantic — embedding-based EU legislation search.
361
+
362
+ Article-level matches (``article_ref``, ``law_id``, ``law_title``,
363
+ ``score``). Same ``min_score`` relevance-floor semantics as
364
+ :meth:`semantic_search`. HyDE is case-law only — the ``hyde`` param
365
+ is ignored by this endpoint, so it is not offered here.
366
+ """
367
+ body = _payloads.semantic_search_body(
368
+ query,
369
+ min_score=min_score,
370
+ limit=limit,
371
+ language=language,
372
+ include_text=include_text,
373
+ filters=filters,
374
+ )
375
+ return self._request(
376
+ "POST", "/legislation/semantic", json=body, cast=SemanticLegislationResponse
377
+ )
378
+
379
+ # ── Export ────────────────────────────────────────────────────────
380
+ def export(
381
+ self,
382
+ *,
383
+ document_type: str | list[str] | None = None,
384
+ author: str | list[str] | None = None,
385
+ subdomain: str | list[str] | None = None,
386
+ language: str | None = None,
387
+ date_from: str | None = None,
388
+ date_to: str | None = None,
389
+ fetched_since: str | None = None,
390
+ include_html: bool | None = None,
391
+ include_content: bool | None = None,
392
+ limit: int | None = None,
393
+ ) -> ExportStream:
394
+ """GET /export — stream matching corpus rows as NDJSON (BUSINESS tier).
395
+
396
+ Returns an :class:`~lexapi.export.ExportStream`: iterate it for one
397
+ dict per corpus row. The leading ``_meta`` envelope and trailing
398
+ ``_done`` line are captured on ``.meta`` / ``.done`` (with
399
+ ``.total`` / ``.streaming`` / ``.truncated`` from the export
400
+ headers). Use it as a context manager to guarantee the connection
401
+ is closed::
402
+
403
+ with client.export(document_type="regulation", limit=1000) as stream:
404
+ for row in stream:
405
+ handle(row["celex"], row.get("parsedContent"))
406
+ print(stream.done, stream.truncated)
407
+
408
+ List filters (``document_type``, ``author``, ``subdomain``) are sent
409
+ comma-separated per the spec. ``fetched_since`` filters on the row's
410
+ ``lastSeenAt`` (ISO date-time) for incremental syncs.
411
+ """
412
+ params = export_params(
413
+ document_type=document_type,
414
+ author=author,
415
+ subdomain=subdomain,
416
+ language=language,
417
+ date_from=date_from,
418
+ date_to=date_to,
419
+ fetched_since=fetched_since,
420
+ include_html=include_html,
421
+ include_content=include_content,
422
+ limit=limit,
423
+ )
424
+ return ExportStream(self._stream_request("GET", "/export", params=params))
425
+
426
+ def _stream_request(
427
+ self, method: str, path: str, *, params: dict[str, Any] | None = None
428
+ ) -> httpx.Response:
429
+ """Send a streaming request with the same retry/error semantics as
430
+ :meth:`_request`; the response body is left unread on success."""
431
+ attempt = 0
432
+ while True:
433
+ request = self._http.build_request(method, path, params=params)
434
+ try:
435
+ response = self._http.send(request, stream=True)
436
+ except httpx.HTTPError as exc:
437
+ wait = exception_retry_wait(exc, attempt, self._retry)
438
+ if wait is None:
439
+ raise transport_error(exc) from exc
440
+ time.sleep(wait)
441
+ attempt += 1
442
+ continue
443
+ if response.is_success:
444
+ return response
445
+ response.read()
446
+ wait = status_retry_wait(method, response, attempt, self._retry)
447
+ if wait is None:
448
+ process_response(response) # raises the typed error
449
+ response.close()
450
+ time.sleep(wait)
451
+ attempt += 1
452
+
453
+ # ── Request core ──────────────────────────────────────────────────
454
+ def _request(
455
+ self,
456
+ method: str,
457
+ path: str,
458
+ *,
459
+ params: dict[str, Any] | None = None,
460
+ json: Any | None = None,
461
+ cast: type[R] = APIResponse, # type: ignore[assignment]
462
+ timeout: float | httpx.Timeout | None = None,
463
+ ) -> R:
464
+ request_kwargs: dict[str, Any] = {"params": params, "json": json}
465
+ if timeout is not None:
466
+ request_kwargs["timeout"] = timeout
467
+ attempt = 0
468
+ while True:
469
+ try:
470
+ response = self._http.request(method, path, **request_kwargs)
471
+ except httpx.HTTPError as exc:
472
+ wait = exception_retry_wait(exc, attempt, self._retry)
473
+ if wait is None:
474
+ raise transport_error(exc) from exc
475
+ time.sleep(wait)
476
+ attempt += 1
477
+ continue
478
+ wait = status_retry_wait(method, response, attempt, self._retry)
479
+ if wait is None:
480
+ return process_response(response, cast)
481
+ time.sleep(wait)
482
+ attempt += 1
483
+
484
+ def close(self) -> None:
485
+ self._http.close()
486
+
487
+ def __enter__(self) -> LexAPI:
488
+ return self
489
+
490
+ def __exit__(self, *exc: object) -> None:
491
+ self.close()