lexapi-client 0.1.0__tar.gz → 0.2.0__tar.gz

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.
Files changed (53) hide show
  1. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/.gitignore +1 -0
  2. lexapi_client-0.2.0/CHANGELOG.md +218 -0
  3. lexapi_client-0.2.0/LICENSE +21 -0
  4. lexapi_client-0.2.0/PKG-INFO +478 -0
  5. lexapi_client-0.2.0/README.md +444 -0
  6. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/pyproject.toml +26 -4
  7. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/__init__.py +45 -2
  8. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/_base.py +65 -23
  9. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/_meta.py +1 -1
  10. lexapi_client-0.2.0/src/lexapi/_payloads.py +293 -0
  11. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/_response.py +93 -6
  12. lexapi_client-0.2.0/src/lexapi/_retry.py +305 -0
  13. lexapi_client-0.2.0/src/lexapi/async_client.py +684 -0
  14. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/citations.py +126 -25
  15. lexapi_client-0.2.0/src/lexapi/client.py +711 -0
  16. lexapi_client-0.2.0/src/lexapi/errors.py +402 -0
  17. lexapi_client-0.2.0/src/lexapi/export.py +447 -0
  18. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/models.py +773 -81
  19. lexapi_client-0.2.0/src/lexapi/webhooks.py +374 -0
  20. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_async_client.py +2 -6
  21. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_citations.py +1 -3
  22. lexapi_client-0.2.0/tests/test_citations_export_v2.py +332 -0
  23. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_client.py +1 -3
  24. lexapi_client-0.2.0/tests/test_documents_v2.py +443 -0
  25. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_errors.py +11 -5
  26. lexapi_client-0.2.0/tests/test_errors_retry_v2.py +258 -0
  27. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_export.py +2 -2
  28. lexapi_client-0.2.0/tests/test_export_failure_ending.py +142 -0
  29. lexapi_client-0.2.0/tests/test_export_params_v23.py +87 -0
  30. lexapi_client-0.2.0/tests/test_quota_exhausted_code.py +125 -0
  31. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_retry.py +2 -4
  32. lexapi_client-0.2.0/tests/test_review_fixes.py +545 -0
  33. lexapi_client-0.2.0/tests/test_review_round2.py +305 -0
  34. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_semantic.py +1 -3
  35. lexapi_client-0.2.0/tests/test_semantic_as_of.py +310 -0
  36. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_webhooks.py +3 -4
  37. lexapi_client-0.2.0/tests/test_webhooks_v2.py +276 -0
  38. lexapi_client-0.1.0/.github/workflows/ci.yml +0 -24
  39. lexapi_client-0.1.0/PKG-INFO +0 -310
  40. lexapi_client-0.1.0/PLAN.md +0 -128
  41. lexapi_client-0.1.0/README.md +0 -288
  42. lexapi_client-0.1.0/src/lexapi/_payloads.py +0 -160
  43. lexapi_client-0.1.0/src/lexapi/_retry.py +0 -148
  44. lexapi_client-0.1.0/src/lexapi/async_client.py +0 -417
  45. lexapi_client-0.1.0/src/lexapi/client.py +0 -491
  46. lexapi_client-0.1.0/src/lexapi/errors.py +0 -261
  47. lexapi_client-0.1.0/src/lexapi/export.py +0 -253
  48. lexapi_client-0.1.0/src/lexapi/webhooks.py +0 -220
  49. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/src/lexapi/py.typed +0 -0
  50. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/conftest.py +0 -0
  51. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_documents_search.py +0 -0
  52. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_point_in_time.py +0 -0
  53. {lexapi_client-0.1.0 → lexapi_client-0.2.0}/tests/test_response.py +0 -0
@@ -12,3 +12,4 @@ htmlcov/
12
12
  .mypy_cache/
13
13
  .DS_Store
14
14
  .env
15
+ .venv*/
@@ -0,0 +1,218 @@
1
+ # Changelog
2
+
3
+ All notable changes to `lexapi-client` (import `lexapi`). The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
5
+ [SemVer](https://semver.org/) (0.x: minors may break, documented here).
6
+
7
+ ## [0.2.0] — 2026-10-26
8
+
9
+ Synced with the LexAPI API as of `openapi.yaml` on lex-api `main` at
10
+ `633eb67` (PR #298). No breaking changes to signatures; behaviour changes are
11
+ listed under **Changed** — read those before upgrading.
12
+
13
+ ### Added
14
+
15
+ - **`semantic_legislation_search(as_of=...)`** — the text in force on a date
16
+ (`YYYY-MM-DD` string or `datetime.date`). New hit fields: `as_of`,
17
+ `as_of_resolved`, `as_of_reason` (see `lexapi.AS_OF_REASONS` /
18
+ `lexapi.AsOfReason`), `as_of_version` (`AsOfVersion`: `celex`, `date`,
19
+ `kind`), `matched_version` (`MatchedVersion`); response fields `as_of` and
20
+ `as_of_summary` (`AsOfSummary`: `live_fetches`, `unresolved`).
21
+ - **Consolidated-text labels on legislation hits:** `consolidated`,
22
+ `consolidated_as_of`, `base_celex`, `consolidated_note`, `base_act`
23
+ (`SemanticBaseAct`), plus `authentic_celex`; and the previously untyped
24
+ `id`, `snippet`, `language`, `chapter`, `section`.
25
+ - **Case-law hits:** `snippet` (the default payload — `text` is only present
26
+ with `include_text=True`), `summary`, `parties` (a list — the upstream
27
+ sends one, without roles; `parties_text` joins it with `"; "` — use
28
+ `case_name` for the citation-style title), `decision_date`,
29
+ `jurisdiction`, `language`, `paragraph_number`. Both semantic responses:
30
+ `max_results`, `upstream_metadata`.
31
+ - **Documents:** `accept_languages` on `get_document` / `get_documents_batch`;
32
+ `bypass_corpus` on `get_document_by_url`; `Document.title_language`,
33
+ `Document.text_availability` (`TextAvailability`, with
34
+ `latest_consolidated` / `upcoming_consolidated` / `newest_consolidated`
35
+ `ConsolidatedVersionHint`s), `Document.text_available`, `fetched_at`,
36
+ `celex_number`, and the metadata endpoint's consolidated hints;
37
+ `DocumentResponse.text_available` (`X-Text-Available`);
38
+ `DocumentBatchResponse.text_unavailable`, `corpus_hits`, `cellar_served`,
39
+ `oj_recovered`, `live_fetches`, `language_served`.
40
+ - **Search:** `fresh=` (bypass the 60-minute result cache);
41
+ `SearchResponse.source` (`X-Search-Source` / body `source`: `soap`,
42
+ `cellar`, `corpus`), `cache` (`X-Search-Cache`), `search_parameters`,
43
+ `post_filtered_kept` (parsed `X-PostFiltered-Kept`: `{"author":
44
+ PostFilterCount(kept=3, before=10), ...}`) and `post_filtered_kept_raw`;
45
+ `SearchHit.celex_number`, `form`, `date_of_document`.
46
+ - **Recent documents:** `author` accepts a list (sent as repeated params);
47
+ `RecentDocumentsResponse.source` (`cellar` / `live`) and `fetched_at`.
48
+ `document_type` and `subdomain` stay **single-valued**: the endpoint has no
49
+ multi-type fan-out and EUR-Lex honours only the first `FM_CODED` /
50
+ `DTS_SUBDOM`, so passing more than one raises `ValueError` instead of being
51
+ silently narrowed (a one-item list is accepted). Use `search()` for
52
+ multi-value filters.
53
+ - **Export:** `include_stubs=`; `ExportStream.written` / `skipped_stubs`
54
+ from the `_done` trailer; `date_from` / `date_to` / `fetched_since` accept
55
+ `datetime` objects.
56
+ - **Webhooks:** watch lists — `create(..., watch_celex=[...])` (criteria now
57
+ optional), `update(watch_celex=..., remove_search_criteria=True)`;
58
+ `Webhook.watch_celex`, `criteria_errors`, `retry_policy`
59
+ (`WebhookRetryPolicy`), `has_search_criteria`;
60
+ `WebhookResponse.requeued_deliveries`; `WebhookDelivery.webhook_id`.
61
+ - **Webhook signature verification:** `verify_webhook()` (signature + replay
62
+ window, returns the event), `verify_signature()`, `compute_signature()`,
63
+ `WebhookSignatureError`.
64
+ - **Citations:** `iter_cited_by()` / `iter_cites()` (walk every edge page);
65
+ `relation_sync` (`RelationSync`) on `cited_by` / `network`;
66
+ `CitationExtractResponse.document`; `title_source` on path nodes and related
67
+ documents; `edge_count` on edge pages.
68
+ - **`/info`:** `get_info()` returns `InfoResponse` (`version`, `endpoints`,
69
+ `search_filters`, `supported_languages`, ...). Every response:
70
+ `subscription_info` (`SubscriptionInfo`) and `rate_limit_limit` /
71
+ `rate_limit_remaining` / `rate_limit_reset` (`RateLimit-*` headers).
72
+ - **Errors:** `CreditsExhaustedError.operation` / `weight` / `available` /
73
+ `included` / `topup` / `used`; `RateLimitedError.quota_exhausted` /
74
+ `resets_at` (legacy daily / semantic quotas); `LexAPIError.upgrade_url`
75
+ (legacy tier gates); legacy bodies' top-level `details` (e.g. the list of
76
+ rejected webhook criteria) is now kept on `err.details`.
77
+ - **`client.with_options(timeout=..., max_retries=..., retry_config=...)`** —
78
+ per-call overrides sharing the connection pool.
79
+ - Path segments (CELEX, webhook ids, dates) are percent-encoded; CELEX
80
+ characters such as `32008R1272R(01)` pass through unchanged.
81
+ - `LICENSE` (MIT) file, Python 3.9–3.14 classifiers, `Typing :: Typed`;
82
+ CI runs 3.9–3.14, `ruff check`, `ruff format --check`, `mypy --strict`,
83
+ and a build + `twine check`. The version is single-sourced in
84
+ `lexapi/_meta.py`; `hatchling>=1.27` is pinned (PEP 639 license field).
85
+ - `RetryConfig(retry_read_only_posts=True)` — opt-in retry of the read-only
86
+ POSTs (search, document reads, resolve, semantic search) on an app-origin
87
+ 502/503/504, which the API refunds in full. Never applies to webhook writes.
88
+ - New error types: `ServiceUnavailableError` (503, code `SERVICE_UNAVAILABLE`,
89
+ subclass of `UpstreamError`), `InvalidResponseError` (2xx whose body is not
90
+ JSON), `IncompleteExportError` (export without its `_done` trailer).
91
+ - `ExportStream.complete`, `rows_read`, `invalid_lines`.
92
+
93
+ ### Changed
94
+
95
+ Retries follow one rule now (PLAN.md §1.2): **retry only when the retry
96
+ cannot charge you twice.** LexAPI refunds a failure only when its own app
97
+ finishes the error response, so proxy errors and dropped connections are not
98
+ refunded.
99
+
100
+ - **Billed GETs no longer retry proxy 502/504 or Cloudflare 520/524**, nor a
101
+ connection dropped after the request was sent (both may already have been
102
+ charged). They still retry app-origin 502/503/504 (refunded), 429, and
103
+ failures that never reached the app. Free calls (`get_info`, webhook reads)
104
+ retry all of these.
105
+ - **Connection failures that never reached the app are retried for every
106
+ method**: connect errors/timeouts, pool timeouts, a stale keep-alive socket
107
+ closed before any response byte, Cloudflare 521/522/523. Previously a stale
108
+ keep-alive disconnect was never retried.
109
+ A connection closed after part of the response arrived is not in that set
110
+ (a billed call may already have been charged).
111
+ - **App origin is decided by headers only** — `X-LexAPI-Version` or the
112
+ limiter's `RateLimit-Limit`; a JSON error body alone no longer counts.
113
+ - **Default timeouts: response 60 s → 95 s, pool 95 s → 10 s.** `timeout` is
114
+ a per-attempt inactivity limit (response head, then each body chunk), not
115
+ a whole-call deadline. 95 s sits above the API's 90 s budget for one
116
+ upstream fetch and below Cloudflare's 100 s. Pass `timeout=60` to keep the
117
+ old value.
118
+ - **A 2xx with a non-JSON body raises `InvalidResponseError`** instead of
119
+ returning an empty, successful response.
120
+ - **503 maps to `SERVICE_UNAVAILABLE`** (`ServiceUnavailableError`, still an
121
+ `UpstreamError`), not `UPSTREAM_ERROR`.
122
+ - **Legacy error bodies:** a string `error` is never read as an error code
123
+ (the code comes from the HTTP status), and `details` is kept on bodies with
124
+ only `message` / `details`.
125
+ - **Numeric retry hints:** values above 1e12 are epoch milliseconds and above
126
+ 1e9 epoch seconds (was: above 1e7 → epoch seconds). `X-RateLimit-Reset` is
127
+ no longer read (the API doesn't send it).
128
+ - **Export streams:** iterating a stream whose `_done` trailer was never
129
+ read raises `IncompleteExportError`, however it was ended (closed early,
130
+ `break`, leaving the `with` block); a fully read stream yields nothing again.
131
+ A mid-stream transport failure raises
132
+ `LexAPIConnectionError` / `RequestTimeoutError` (was: a raw `httpx`
133
+ exception); a missing `_done` trailer raises `IncompleteExportError`;
134
+ `truncated` no longer reports skipped stub rows as truncation.
135
+ - **`webhooks.iter_deliveries` yields each delivery once** (deduplicated on
136
+ `id`) when new deliveries shift the pages.
137
+ - **Empty, `.` and `..` path segments raise `ValueError`** (httpx would
138
+ resolve `..` to the parent endpoint).
139
+ - **Retry waits no longer use `RateLimit-Reset` outside a 429.** LexAPI sends
140
+ `RateLimit-*` on every response, so a retried 502/503/504 used to sleep for
141
+ the rate-limit window (up to the 30 s cap) instead of the computed backoff;
142
+ `err.retry_after` on non-429 errors was set from the same header.
143
+ `Retry-After` is still honoured on any status.
144
+ - **A legacy-plan 429 for an exhausted quota is no longer retried** (body
145
+ carries `usage.resetsAt` and no `retryAfter`) — it cannot succeed before
146
+ the reset — and its `retry_after` is `None` (it used to show the 60 s rate
147
+ window). Rate-limit 429s are retried as before.
148
+ - **Cloudflare 520–524** are mapped to `UpstreamError` (520–523) /
149
+ `TimeoutError` (524) instead of a generic `LexAPIError` with code
150
+ `INTERNAL`; which of them are retried follows the rule above.
151
+ - `get_info()` returns `InfoResponse` (an `APIResponse` subclass — mapping
152
+ access is unchanged).
153
+
154
+ ### Deprecated
155
+
156
+ - `Webhook.max_retries` — the API no longer sends `maxRetries`, so it is
157
+ always `None`; reading it emits a `DeprecationWarning` (only on your own
158
+ attribute access — not from `dataclasses.asdict`/`replace`, repr, equality,
159
+ copy or pickle). Read
160
+ `Webhook.retry_policy.max_attempts` (on `webhooks.get()`).
161
+
162
+ ### Fixed
163
+
164
+ - Docstrings and README now match the API: `X-Source` values include
165
+ `cellar` / `cellar-oj`; document reads settle at 1 (corpus) / 4 (Cellar) /
166
+ 5 (browser) credits; `/export` below BUSINESS is a 403
167
+ `TierForbiddenError` (with `upgrade_url`), not a 402; `DELETE /webhooks/{id}`
168
+ answers 200 with a JSON body (still returns `None`); README no longer
169
+ describes the package as an unpublished scaffold.
170
+ - `mypy` now passes on the package, in strict mode.
171
+ - `verify_signature` returns `False` for a non-ASCII signature header instead
172
+ of raising `TypeError` (anyone can send such a header to a public receiver).
173
+ - `with_options(connect_timeout=...)` alone now takes effect (it was ignored
174
+ unless `timeout` was also passed).
175
+ - Docstrings: batch live items without text bill 1 credit; semantic case-law
176
+ `limit` caps are FREE 10 / STARTER 20 / PROFESSIONAL 50 / BUSINESS+ 100;
177
+ recent documents are admitted against `ceil(limit / 10)` pages; the export
178
+ docs no longer state a per-row price (see the pricing page).
179
+ - **Export streams never report a failed export as complete.** A `_done`
180
+ trailer that says `"complete": false`, or any line whose only key is
181
+ `_error`, now raises `IncompleteExportError` (after the rows that did
182
+ arrive) and leaves `stream.complete` false; before, any `_done` line counted
183
+ as complete and an `_error` line was yielded as a document row. The error
184
+ line's `code` / `message` are on the exception's `details` and on the new
185
+ `stream.error`. Unknown `_done` fields (`truncatedBy`, `credits`) are kept
186
+ on `stream.done`. (PLAN.md §1.8; lex-api #303.)
187
+ - **Top-level `code` on legacy-shape error bodies, and `QUOTA_EXHAUSTED`.**
188
+ When an error body carries a top-level string `code` (lex-api #304 adds it
189
+ next to the legacy text `error`), it is the error's `code`, ahead of the
190
+ status-derived one. A 429 with `code: "QUOTA_EXHAUSTED"` (a legacy plan's
191
+ used-up daily or monthly-semantic quota) raises `RateLimitedError` with
192
+ `code == "QUOTA_EXHAUSTED"`, `quota_exhausted` true, `retry_after` `None`
193
+ and `resets_at` from the body's `resetsAt`; it is never retried. Servers
194
+ without the `code` are still recognised by the old shape check.
195
+ (PLAN.md §1.2/§1.3.)
196
+ - **Export parameters for API 2.3.0** (lex-api #303): `document_type_code`
197
+ (a type family) and `changed_since` (rows whose text changed), on `export()`
198
+ of both clients. A naive `datetime` for `fetched_since` / `changed_since`
199
+ and a `limit` that is not a positive integer raise `ValueError` before the
200
+ request (the API answers 400 to both). Docstrings and README describe the
201
+ per-row billing and the filter semantics of API 2.3.0. **Publish only after
202
+ lex-api #303 is deployed.**
203
+ - **`stream.truncated` reads `_done.truncated` first once the trailer has
204
+ been read.** From API 2.3.0 that flag is authoritative: it is set when
205
+ matching rows remain unreached (`truncatedBy`: `limit`, `max_rows`, `recovered` or
206
+ `credits`) and never derived from the row count. The `X-Export-Truncated`
207
+ header and `_meta.truncated` come from an up-front count that may be a
208
+ minute old and never caps the stream, so they are now only the fallback
209
+ before the trailer arrives. (PLAN.md §1.8; lex-api #303.)
210
+
211
+ ## [0.1.0] — 2026-07-02
212
+
213
+ First release on PyPI: sync + async clients, typed models, typed errors,
214
+ retries, credit visibility, search, documents, versions, semantic search
215
+ (with HyDE), citations, webhooks, NDJSON export.
216
+
217
+ [0.2.0]: https://github.com/Lex-API/lexapi-python/compare/523235a...v0.2.0
218
+ [0.1.0]: https://github.com/Lex-API/lexapi-python/tree/523235a
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arieta Labs Ltd
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.