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/citations.py ADDED
@@ -0,0 +1,231 @@
1
+ """Citation-graph resource namespace: ``client.citations.*``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ from lexapi._payloads import drop_none
8
+ from lexapi.models import (
9
+ CitationExtractResponse,
10
+ CitationNetworkResponse,
11
+ CitationPathResponse,
12
+ CitationStatsResponse,
13
+ CitedByResponse,
14
+ CitesResponse,
15
+ RelatedDocumentsResponse,
16
+ )
17
+
18
+ if TYPE_CHECKING: # pragma: no cover
19
+ from lexapi.async_client import AsyncLexAPI
20
+ from lexapi.client import LexAPI
21
+
22
+
23
+ def _edge_params(
24
+ citation_type: str | None, limit: int | None, offset: int | None
25
+ ) -> dict:
26
+ return drop_none({"citationType": citation_type, "limit": limit, "offset": offset})
27
+
28
+
29
+ class CitationsResource:
30
+ """Synchronous ``/citations/*`` operations (``client.citations``)."""
31
+
32
+ def __init__(self, client: LexAPI) -> None:
33
+ self._client = client
34
+
35
+ def extract(self, celex: str) -> CitationExtractResponse:
36
+ """POST /citations/extract — crawl a document's metadata page and
37
+ persist its citation edges.
38
+
39
+ Idempotent: if already extracted, returns immediately with
40
+ ``already_extracted=True`` and an empty ``citations`` list.
41
+ """
42
+ return self._client._request(
43
+ "POST",
44
+ "/citations/extract",
45
+ json={"celexNumber": celex},
46
+ cast=CitationExtractResponse,
47
+ )
48
+
49
+ def cited_by(
50
+ self,
51
+ celex: str,
52
+ *,
53
+ citation_type: str | None = None,
54
+ limit: int | None = None,
55
+ offset: int | None = None,
56
+ ) -> CitedByResponse:
57
+ """GET /citations/cited-by/{celex} — inbound edges (documents citing this one).
58
+
59
+ Paginated in edges via ``limit``/``offset``; ``total_citations``
60
+ counts all pages.
61
+ """
62
+ return self._client._request(
63
+ "GET",
64
+ f"/citations/cited-by/{celex}",
65
+ params=_edge_params(citation_type, limit, offset),
66
+ cast=CitedByResponse,
67
+ )
68
+
69
+ def cites(
70
+ self,
71
+ celex: str,
72
+ *,
73
+ citation_type: str | None = None,
74
+ limit: int | None = None,
75
+ offset: int | None = None,
76
+ ) -> CitesResponse:
77
+ """GET /citations/cites/{celex} — outbound edges (documents this one cites).
78
+
79
+ A document must have been crawled via :meth:`extract` to appear here.
80
+ """
81
+ return self._client._request(
82
+ "GET",
83
+ f"/citations/cites/{celex}",
84
+ params=_edge_params(citation_type, limit, offset),
85
+ cast=CitesResponse,
86
+ )
87
+
88
+ def network(
89
+ self,
90
+ celex: str,
91
+ *,
92
+ citation_type: str | None = None,
93
+ limit: int | None = None,
94
+ offset: int | None = None,
95
+ ) -> CitationNetworkResponse:
96
+ """GET /citations/network/{celex} — both directions in one call.
97
+
98
+ ``limit`` applies per direction (max 500). On server-side budget
99
+ expiry the response is still 200 with ``partial=True`` and empty
100
+ arrays — always check ``response.partial``.
101
+ """
102
+ return self._client._request(
103
+ "GET",
104
+ f"/citations/network/{celex}",
105
+ params=_edge_params(citation_type, limit, offset),
106
+ cast=CitationNetworkResponse,
107
+ )
108
+
109
+ def path(
110
+ self, from_celex: str, to_celex: str, *, max_depth: int | None = None
111
+ ) -> CitationPathResponse:
112
+ """GET /citations/path/{from}/{to} — shortest citation path (BFS).
113
+
114
+ No path within the budget is a graceful ``found=False`` response
115
+ (HTTP 200), not an error. ``max_depth`` defaults to 3 (max 8).
116
+ """
117
+ return self._client._request(
118
+ "GET",
119
+ f"/citations/path/{from_celex}/{to_celex}",
120
+ params=drop_none({"maxDepth": max_depth}),
121
+ cast=CitationPathResponse,
122
+ )
123
+
124
+ def related(self, celex: str, *, limit: int | None = None) -> RelatedDocumentsResponse:
125
+ """GET /citations/related/{celex} — bibliographic-coupling neighbours.
126
+
127
+ Seeds with no outbound citations return an empty list plus a
128
+ ``message`` (graceful, not an error).
129
+ """
130
+ return self._client._request(
131
+ "GET",
132
+ f"/citations/related/{celex}",
133
+ params=drop_none({"limit": limit}),
134
+ cast=RelatedDocumentsResponse,
135
+ )
136
+
137
+ def stats(self) -> CitationStatsResponse:
138
+ """GET /citations/stats — global citation-graph counters and top-10s."""
139
+ return self._client._request("GET", "/citations/stats", cast=CitationStatsResponse)
140
+
141
+
142
+ class AsyncCitationsResource:
143
+ """Asynchronous ``/citations/*`` operations (``client.citations``)."""
144
+
145
+ def __init__(self, client: AsyncLexAPI) -> None:
146
+ self._client = client
147
+
148
+ async def extract(self, celex: str) -> CitationExtractResponse:
149
+ """POST /citations/extract — see :meth:`CitationsResource.extract`."""
150
+ return await self._client._request(
151
+ "POST",
152
+ "/citations/extract",
153
+ json={"celexNumber": celex},
154
+ cast=CitationExtractResponse,
155
+ )
156
+
157
+ async def cited_by(
158
+ self,
159
+ celex: str,
160
+ *,
161
+ citation_type: str | None = None,
162
+ limit: int | None = None,
163
+ offset: int | None = None,
164
+ ) -> CitedByResponse:
165
+ """GET /citations/cited-by/{celex} — see :meth:`CitationsResource.cited_by`."""
166
+ return await self._client._request(
167
+ "GET",
168
+ f"/citations/cited-by/{celex}",
169
+ params=_edge_params(citation_type, limit, offset),
170
+ cast=CitedByResponse,
171
+ )
172
+
173
+ async def cites(
174
+ self,
175
+ celex: str,
176
+ *,
177
+ citation_type: str | None = None,
178
+ limit: int | None = None,
179
+ offset: int | None = None,
180
+ ) -> CitesResponse:
181
+ """GET /citations/cites/{celex} — see :meth:`CitationsResource.cites`."""
182
+ return await self._client._request(
183
+ "GET",
184
+ f"/citations/cites/{celex}",
185
+ params=_edge_params(citation_type, limit, offset),
186
+ cast=CitesResponse,
187
+ )
188
+
189
+ async def network(
190
+ self,
191
+ celex: str,
192
+ *,
193
+ citation_type: str | None = None,
194
+ limit: int | None = None,
195
+ offset: int | None = None,
196
+ ) -> CitationNetworkResponse:
197
+ """GET /citations/network/{celex} — see :meth:`CitationsResource.network`."""
198
+ return await self._client._request(
199
+ "GET",
200
+ f"/citations/network/{celex}",
201
+ params=_edge_params(citation_type, limit, offset),
202
+ cast=CitationNetworkResponse,
203
+ )
204
+
205
+ async def path(
206
+ self, from_celex: str, to_celex: str, *, max_depth: int | None = None
207
+ ) -> CitationPathResponse:
208
+ """GET /citations/path/{from}/{to} — see :meth:`CitationsResource.path`."""
209
+ return await self._client._request(
210
+ "GET",
211
+ f"/citations/path/{from_celex}/{to_celex}",
212
+ params=drop_none({"maxDepth": max_depth}),
213
+ cast=CitationPathResponse,
214
+ )
215
+
216
+ async def related(
217
+ self, celex: str, *, limit: int | None = None
218
+ ) -> RelatedDocumentsResponse:
219
+ """GET /citations/related/{celex} — see :meth:`CitationsResource.related`."""
220
+ return await self._client._request(
221
+ "GET",
222
+ f"/citations/related/{celex}",
223
+ params=drop_none({"limit": limit}),
224
+ cast=RelatedDocumentsResponse,
225
+ )
226
+
227
+ async def stats(self) -> CitationStatsResponse:
228
+ """GET /citations/stats — see :meth:`CitationsResource.stats`."""
229
+ return await self._client._request(
230
+ "GET", "/citations/stats", cast=CitationStatsResponse
231
+ )