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/errors.py ADDED
@@ -0,0 +1,261 @@
1
+ """Typed errors mirroring the LexAPI error envelope.
2
+
3
+ The API's canonical envelope is::
4
+
5
+ {"success": false, "error": {"code": "NOT_FOUND", "message": "...", "details": {...}}}
6
+
7
+ Some legacy endpoints return a bare ``{"error": "...", "message": "..."}`` body
8
+ with string values; the parser tolerates both shapes. Unknown ``error.code``
9
+ values never crash the parser — the raw code string is preserved on the
10
+ generic :class:`LexAPIError` (forward compatibility).
11
+
12
+ Two distinct "timeout" errors exist by design:
13
+
14
+ - :class:`TimeoutError` — the *server's* typed 504 ``TIMEOUT`` envelope
15
+ (upstream EUR-Lex fetch timed out; the spec marks it retry-safe).
16
+ - :class:`RequestTimeoutError` — the *SDK's* local httpx timeout (the
17
+ response never arrived).
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from typing import Any
23
+
24
+ #: Fallback mapping used when the body carries no typed ``error.code``
25
+ #: (legacy bare ``{"error": "..."}`` shape, or non-JSON bodies).
26
+ STATUS_TO_CODE = {
27
+ 400: "INVALID_PARAMS",
28
+ 401: "UNAUTHORIZED",
29
+ 402: "CREDITS_EXHAUSTED",
30
+ 403: "TIER_FORBIDDEN",
31
+ 404: "NOT_FOUND",
32
+ 429: "RATE_LIMITED",
33
+ 500: "INTERNAL",
34
+ 502: "UPSTREAM_ERROR",
35
+ 503: "UPSTREAM_ERROR",
36
+ 504: "TIMEOUT",
37
+ }
38
+
39
+
40
+ class LexAPIError(Exception):
41
+ """Base error for any failed LexAPI call.
42
+
43
+ Attributes:
44
+ code: stable machine-readable slug (``NOT_FOUND``, ``RATE_LIMITED``, ...).
45
+ Unknown codes from newer API versions are preserved as-is.
46
+ message: human-readable description from the API.
47
+ status: HTTP status code (``None`` for transport-level failures).
48
+ details: the ``error.details`` object when present.
49
+ body: the raw decoded response body (``None`` if not JSON).
50
+ retry_after: seconds to wait before retrying, when the server said so.
51
+ """
52
+
53
+ default_code = "UNKNOWN"
54
+
55
+ def __init__(
56
+ self,
57
+ message: str,
58
+ *,
59
+ code: str | None = None,
60
+ status: int | None = None,
61
+ details: Any | None = None,
62
+ body: Any | None = None,
63
+ retry_after: float | None = None,
64
+ ) -> None:
65
+ code = code or self.default_code
66
+ suffix = f" (HTTP {status})" if status is not None else ""
67
+ super().__init__(f"[{code}] {message}{suffix}")
68
+ self.code = code
69
+ self.message = message
70
+ self.status = status
71
+ self.details = details
72
+ self.body = body
73
+ self.retry_after = retry_after
74
+
75
+ @classmethod
76
+ def from_response(
77
+ cls, status: int, body: Any, retry_after: float | None = None
78
+ ) -> LexAPIError:
79
+ """Build the most specific typed error for a non-2xx response."""
80
+ return error_from_response(status, body, retry_after=retry_after)
81
+
82
+
83
+ class AuthenticationError(LexAPIError):
84
+ """401 — missing, invalid, or revoked API key."""
85
+
86
+ default_code = "UNAUTHORIZED"
87
+
88
+
89
+ class InvalidParamsError(LexAPIError):
90
+ """400 ``INVALID_PARAMS`` — missing or malformed parameters."""
91
+
92
+ default_code = "INVALID_PARAMS"
93
+
94
+
95
+ class InvalidCelexError(LexAPIError):
96
+ """400 ``INVALID_CELEX`` — CELEX identifier failed validation."""
97
+
98
+ default_code = "INVALID_CELEX"
99
+
100
+
101
+ class InvalidURLError(LexAPIError):
102
+ """400 ``INVALID_URL`` — URL had no resolvable CELEX."""
103
+
104
+ default_code = "INVALID_URL"
105
+
106
+
107
+ class NotFoundError(LexAPIError):
108
+ """404 ``NOT_FOUND`` — document or resource missing."""
109
+
110
+ default_code = "NOT_FOUND"
111
+
112
+
113
+ class RateLimitedError(LexAPIError):
114
+ """429 ``RATE_LIMITED`` — quota or rate ceiling hit.
115
+
116
+ ``retry_after`` carries the server-directed wait in seconds when the
117
+ server provided one (``Retry-After`` header preferred; see
118
+ :mod:`lexapi._retry` for the resolution order).
119
+ """
120
+
121
+ default_code = "RATE_LIMITED"
122
+
123
+
124
+ class TierForbiddenError(LexAPIError):
125
+ """403 ``TIER_FORBIDDEN`` — endpoint not included in the caller's tier."""
126
+
127
+ default_code = "TIER_FORBIDDEN"
128
+
129
+
130
+ class CreditsExhaustedError(LexAPIError):
131
+ """402 ``CREDITS_EXHAUSTED`` — monthly credit pool exhausted (pricing v2).
132
+
133
+ ``resets_at`` is the ISO-8601 timestamp when the monthly allowance
134
+ resets, when the server reported one. Retrying cannot help until
135
+ top-up or the next cycle anchor.
136
+ """
137
+
138
+ default_code = "CREDITS_EXHAUSTED"
139
+
140
+ def __init__(self, message: str, *, resets_at: str | None = None, **kwargs: Any) -> None:
141
+ super().__init__(message, **kwargs)
142
+ self.resets_at = resets_at
143
+
144
+
145
+ class UpstreamError(LexAPIError):
146
+ """502 ``UPSTREAM_ERROR`` — EUR-Lex returned an error."""
147
+
148
+ default_code = "UPSTREAM_ERROR"
149
+
150
+
151
+ class TimeoutError(LexAPIError): # noqa: A001 - mirrors the API's TIMEOUT code
152
+ """504 ``TIMEOUT`` — the upstream EUR-Lex fetch timed out (retry-safe)."""
153
+
154
+ default_code = "TIMEOUT"
155
+
156
+
157
+ class InternalServerError(LexAPIError):
158
+ """500 ``INTERNAL`` — unexpected server failure."""
159
+
160
+ default_code = "INTERNAL"
161
+
162
+
163
+ class LexAPIConnectionError(LexAPIError):
164
+ """Transport-level failure — the HTTP exchange never completed."""
165
+
166
+ default_code = "CONNECTION_ERROR"
167
+
168
+ def __init__(self, message: str, **kwargs: Any) -> None:
169
+ kwargs.setdefault("status", None)
170
+ super().__init__(message, **kwargs)
171
+
172
+
173
+ class RequestTimeoutError(LexAPIConnectionError):
174
+ """The SDK's local timeout elapsed before a response arrived.
175
+
176
+ Distinct from :class:`TimeoutError`, which is the server's typed 504.
177
+ """
178
+
179
+ default_code = "REQUEST_TIMEOUT"
180
+
181
+
182
+ CODE_TO_ERROR: dict[str, type[LexAPIError]] = {
183
+ "UNAUTHORIZED": AuthenticationError,
184
+ "INVALID_PARAMS": InvalidParamsError,
185
+ "INVALID_CELEX": InvalidCelexError,
186
+ "INVALID_URL": InvalidURLError,
187
+ "NOT_FOUND": NotFoundError,
188
+ "RATE_LIMITED": RateLimitedError,
189
+ "TIER_FORBIDDEN": TierForbiddenError,
190
+ "CREDITS_EXHAUSTED": CreditsExhaustedError,
191
+ "UPSTREAM_ERROR": UpstreamError,
192
+ "TIMEOUT": TimeoutError,
193
+ "INTERNAL": InternalServerError,
194
+ }
195
+
196
+
197
+ def _extract_resets_at(details: Any, body: Any) -> str | None:
198
+ """Best-effort ``resetsAt`` for CREDITS_EXHAUSTED errors.
199
+
200
+ The spec says the 402 ``details`` includes the pool state and
201
+ ``resetsAt``; some responses also carry top-level ``usage`` / ``credits``
202
+ blocks. Checked in that order.
203
+ """
204
+ for container in (details, body):
205
+ if not isinstance(container, dict):
206
+ continue
207
+ value = container.get("resetsAt")
208
+ if isinstance(value, str):
209
+ return value
210
+ for key in ("credits", "usage"):
211
+ block = container.get(key)
212
+ if isinstance(block, dict) and isinstance(block.get("resetsAt"), str):
213
+ return block["resetsAt"]
214
+ return None
215
+
216
+
217
+ def error_from_response(
218
+ status: int, body: Any, retry_after: float | None = None
219
+ ) -> LexAPIError:
220
+ """Map a non-2xx response to the most specific typed error.
221
+
222
+ Tolerates both envelope shapes:
223
+
224
+ - typed: ``{"success": false, "error": {"code", "message", "details"}}``
225
+ - legacy: ``{"error": "<slug or text>", "message": "..."}`` (both strings)
226
+
227
+ Unknown ``error.code`` values fall back to the base :class:`LexAPIError`
228
+ with the raw code preserved.
229
+ """
230
+ code = STATUS_TO_CODE.get(status, "INTERNAL")
231
+ message = f"HTTP {status}"
232
+ details: Any | None = None
233
+ if isinstance(body, dict):
234
+ err = body.get("error")
235
+ if isinstance(err, dict): # typed envelope
236
+ code = err.get("code") or code
237
+ message = err.get("message") or message
238
+ details = err.get("details")
239
+ elif isinstance(err, str): # legacy bare {"error": "...", "message": "..."}
240
+ legacy_message = body.get("message")
241
+ if err in CODE_TO_ERROR: # some legacy bodies carry the slug in `error`
242
+ code = err
243
+ message = legacy_message if isinstance(legacy_message, str) else message
244
+ else:
245
+ message = err
246
+ if isinstance(legacy_message, str):
247
+ message = f"{err}: {legacy_message}" if legacy_message != err else err
248
+ elif isinstance(body.get("message"), str):
249
+ message = body["message"]
250
+
251
+ error_cls = CODE_TO_ERROR.get(code, LexAPIError)
252
+ kwargs: dict[str, Any] = {
253
+ "code": code,
254
+ "status": status,
255
+ "details": details,
256
+ "body": body,
257
+ "retry_after": retry_after,
258
+ }
259
+ if error_cls is CreditsExhaustedError:
260
+ kwargs["resets_at"] = _extract_resets_at(details, body)
261
+ return error_cls(message, **kwargs)
lexapi/export.py ADDED
@@ -0,0 +1,253 @@
1
+ """Streaming NDJSON corpus export (``GET /export``, BUSINESS tier).
2
+
3
+ The wire format is: a leading ``_meta`` envelope line, one JSON document
4
+ per line, then a trailing ``_done`` line. :class:`ExportStream` /
5
+ :class:`AsyncExportStream` iterate the *document* rows and capture the
6
+ ``_meta`` / ``_done`` envelopes as attributes:
7
+
8
+ - ``stream.meta`` — the ``_meta`` envelope. Populated as soon as the first
9
+ line is read; call ``read_meta()`` / ``await read_meta()`` to fetch it
10
+ eagerly before iterating (no document rows are lost).
11
+ - ``stream.done`` — the ``_done`` trailer, populated once the iterator is
12
+ exhausted; carries ``truncated: true`` when the server row cap was hit.
13
+ - ``stream.total`` / ``stream.streaming`` / ``stream.truncated`` — from the
14
+ ``X-Export-Total`` / ``X-Export-Streaming`` / ``X-Export-Truncated``
15
+ response headers, available immediately.
16
+
17
+ Both classes are context managers; the underlying HTTP response is closed
18
+ when iteration finishes, on ``close()``/``aclose()``, or on context exit.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import json
24
+ from collections.abc import AsyncIterator, Iterator
25
+ from typing import Any
26
+
27
+ import httpx
28
+
29
+ from lexapi._payloads import drop_none
30
+
31
+
32
+ def export_params(
33
+ *,
34
+ document_type: str | list[str] | None = None,
35
+ author: str | list[str] | None = None,
36
+ subdomain: str | list[str] | None = None,
37
+ language: str | None = None,
38
+ date_from: str | None = None,
39
+ date_to: str | None = None,
40
+ fetched_since: str | None = None,
41
+ include_html: bool | None = None,
42
+ include_content: bool | None = None,
43
+ limit: int | None = None,
44
+ ) -> dict[str, Any]:
45
+ """Query params for /export. List values are joined comma-separated."""
46
+
47
+ def _join(value: str | list[str] | None) -> str | None:
48
+ if isinstance(value, list):
49
+ return ",".join(value)
50
+ return value
51
+
52
+ return drop_none(
53
+ {
54
+ "documentType": _join(document_type),
55
+ "author": _join(author),
56
+ "subdomain": _join(subdomain),
57
+ "language": language,
58
+ "dateFrom": date_from,
59
+ "dateTo": date_to,
60
+ "fetchedSince": fetched_since,
61
+ "includeHtml": include_html,
62
+ "includeContent": include_content,
63
+ "limit": limit,
64
+ }
65
+ )
66
+
67
+
68
+ def _envelope(row: dict, key: str) -> dict:
69
+ """Extract the ``_meta`` / ``_done`` envelope from its line.
70
+
71
+ Tolerates both ``{"_meta": {...}}`` (nested) and ``{"_meta": true, ...}``
72
+ (flat) line shapes.
73
+ """
74
+ value = row.get(key)
75
+ return value if isinstance(value, dict) else row
76
+
77
+
78
+ class _ExportStreamBase:
79
+ def __init__(self, response: httpx.Response) -> None:
80
+ self._response = response
81
+ self._finished = False
82
+ self._pending: list[dict] = []
83
+ #: The leading ``_meta`` envelope (populated once the stream is read).
84
+ self.meta: dict | None = None
85
+ #: The trailing ``_done`` envelope (populated when iteration completes).
86
+ self.done: dict | None = None
87
+ self.headers = response.headers
88
+
89
+ @property
90
+ def total(self) -> int | None:
91
+ """Total rows matching the filters in the database (X-Export-Total)."""
92
+ return self._header_int("x-export-total")
93
+
94
+ @property
95
+ def streaming(self) -> int | None:
96
+ """Rows actually streamed — min(total, limit) (X-Export-Streaming)."""
97
+ return self._header_int("x-export-streaming")
98
+
99
+ @property
100
+ def truncated(self) -> bool:
101
+ """True when the server row cap was hit (header, or ``_done`` trailer)."""
102
+ if self.headers.get("x-export-truncated") == "1":
103
+ return True
104
+ if isinstance(self.done, dict) and self.done.get("truncated") is True:
105
+ return True
106
+ return False
107
+
108
+ def _header_int(self, name: str) -> int | None:
109
+ value = self.headers.get(name)
110
+ if value is None:
111
+ return None
112
+ try:
113
+ return int(value)
114
+ except ValueError:
115
+ return None
116
+
117
+ def _classify(self, line: str) -> tuple[str, dict] | None:
118
+ """Sort a raw NDJSON line into ("meta"|"done"|"row", payload)."""
119
+ line = line.strip()
120
+ if not line:
121
+ return None
122
+ try:
123
+ row = json.loads(line)
124
+ except ValueError:
125
+ return None
126
+ if not isinstance(row, dict):
127
+ return None
128
+ if self.meta is None and self.done is None and "_meta" in row:
129
+ self.meta = _envelope(row, "_meta")
130
+ return ("meta", self.meta)
131
+ if "_done" in row:
132
+ self.done = _envelope(row, "_done")
133
+ return ("done", self.done)
134
+ return ("row", row)
135
+
136
+
137
+ class ExportStream(_ExportStreamBase):
138
+ """Iterator over export document rows (one dict per corpus row)."""
139
+
140
+ def __init__(self, response: httpx.Response) -> None:
141
+ super().__init__(response)
142
+ self._lines: Iterator[str] | None = None
143
+
144
+ def _line_iter(self) -> Iterator[str]:
145
+ if self._lines is None:
146
+ self._lines = self._response.iter_lines()
147
+ return self._lines
148
+
149
+ def read_meta(self) -> dict | None:
150
+ """Eagerly read the leading ``_meta`` envelope before iterating.
151
+
152
+ Any document row encountered instead (no ``_meta`` line) is buffered
153
+ and yielded first by iteration — nothing is lost. Returns ``None``
154
+ when the stream carries no ``_meta`` envelope.
155
+ """
156
+ if self.meta is not None or self._finished:
157
+ return self.meta
158
+ for line in self._line_iter():
159
+ kind = self._classify(line)
160
+ if kind is None:
161
+ continue
162
+ if kind[0] == "meta":
163
+ return self.meta
164
+ if kind[0] == "done":
165
+ self.close()
166
+ return self.meta
167
+ self._pending.append(kind[1])
168
+ return self.meta
169
+ return self.meta
170
+
171
+ def __iter__(self) -> Iterator[dict]:
172
+ try:
173
+ while self._pending:
174
+ yield self._pending.pop(0)
175
+ if self._finished:
176
+ return
177
+ for line in self._line_iter():
178
+ kind = self._classify(line)
179
+ if kind is None or kind[0] == "meta":
180
+ continue
181
+ if kind[0] == "done":
182
+ break
183
+ yield kind[1]
184
+ finally:
185
+ self.close()
186
+
187
+ def close(self) -> None:
188
+ if not self._finished:
189
+ self._finished = True
190
+ self._response.close()
191
+
192
+ def __enter__(self) -> ExportStream:
193
+ return self
194
+
195
+ def __exit__(self, *exc: object) -> None:
196
+ self.close()
197
+
198
+
199
+ class AsyncExportStream(_ExportStreamBase):
200
+ """Async iterator over export document rows."""
201
+
202
+ def __init__(self, response: httpx.Response) -> None:
203
+ super().__init__(response)
204
+ self._lines: AsyncIterator[str] | None = None
205
+
206
+ def _line_iter(self) -> AsyncIterator[str]:
207
+ if self._lines is None:
208
+ self._lines = self._response.aiter_lines()
209
+ return self._lines
210
+
211
+ async def read_meta(self) -> dict | None:
212
+ """Async twin of :meth:`ExportStream.read_meta`."""
213
+ if self.meta is not None or self._finished:
214
+ return self.meta
215
+ async for line in self._line_iter():
216
+ kind = self._classify(line)
217
+ if kind is None:
218
+ continue
219
+ if kind[0] == "meta":
220
+ return self.meta
221
+ if kind[0] == "done":
222
+ await self.aclose()
223
+ return self.meta
224
+ self._pending.append(kind[1])
225
+ return self.meta
226
+ return self.meta
227
+
228
+ async def __aiter__(self) -> AsyncIterator[dict]:
229
+ try:
230
+ while self._pending:
231
+ yield self._pending.pop(0)
232
+ if self._finished:
233
+ return
234
+ async for line in self._line_iter():
235
+ kind = self._classify(line)
236
+ if kind is None or kind[0] == "meta":
237
+ continue
238
+ if kind[0] == "done":
239
+ break
240
+ yield kind[1]
241
+ finally:
242
+ await self.aclose()
243
+
244
+ async def aclose(self) -> None:
245
+ if not self._finished:
246
+ self._finished = True
247
+ await self._response.aclose()
248
+
249
+ async def __aenter__(self) -> AsyncExportStream:
250
+ return self
251
+
252
+ async def __aexit__(self, *exc: object) -> None:
253
+ await self.aclose()