trialmap 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.
trialmap/client.py ADDED
@@ -0,0 +1,487 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Client for the ClinicalTrials.gov v2 REST API (https://clinicaltrials.gov/data-api/api)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import logging
7
+ import warnings
8
+ from collections.abc import Iterator, Sequence
9
+ from typing import TYPE_CHECKING, Any, Literal, cast, overload
10
+
11
+ import httpx
12
+
13
+ from ._http import HttpClient
14
+ from .enums import FieldStatsType
15
+ from .models import (
16
+ EnumInfoDict,
17
+ FieldNodeDict,
18
+ FieldValuesStatsDict,
19
+ GzipStatsDict,
20
+ ListSizesDict,
21
+ PagedStudiesDict,
22
+ SearchDocumentDict,
23
+ StudiesPage,
24
+ Study,
25
+ StudyDict,
26
+ VersionDict,
27
+ )
28
+ from .query import StudyQuery, StudyQueryParams, _serialise
29
+
30
+ if TYPE_CHECKING:
31
+ from types import TracebackType
32
+
33
+ from typing_extensions import Self, Unpack
34
+
35
+ __all__ = ["BASE_URL", "MAX_PAGE_SIZE", "CTGovClient"]
36
+
37
+ log = logging.getLogger("trialmap.client")
38
+
39
+ BASE_URL = "https://clinicaltrials.gov/api/v2"
40
+ MAX_PAGE_SIZE = 1000
41
+ """The API silently coerces larger ``pageSize`` values down to this."""
42
+
43
+ MarkupFormat = Literal["markdown", "legacy"]
44
+ SingleStudyFormat = Literal["json", "csv", "json.zip", "fhir.json", "ris"]
45
+
46
+
47
+ class CTGovClient:
48
+ """ClinicalTrials.gov v2 API client.
49
+
50
+ >>> with CTGovClient() as ct: # doctest: +SKIP
51
+ ... for study in ct.iter_studies(query_intr="methotrexate", max_studies=50):
52
+ ... print(study.nct_id, study.overall_status, study.phases)
53
+
54
+ Args:
55
+ user_agent: optional; sent with every request. Defaults to ``trialmap/<version> ...``.
56
+ timeout: per-request timeout in seconds.
57
+ max_retries: retries on HTTP 429/5xx and network errors, with exponential backoff
58
+ (``Retry-After`` honoured).
59
+ backoff_factor: base of the exponential backoff, in seconds.
60
+ rate_limit: max requests per second (``None`` disables). The API's limit is not
61
+ published in machine-readable form; the conservative default avoids 429s.
62
+ base_url: override for testing/mirrors.
63
+ transport: custom httpx transport (e.g. ``httpx.MockTransport`` in tests).
64
+ """
65
+
66
+ def __init__(
67
+ self,
68
+ *,
69
+ user_agent: str | None = None,
70
+ timeout: float = 60.0,
71
+ max_retries: int = 4,
72
+ backoff_factor: float = 1.0,
73
+ rate_limit: float | None = 2.0,
74
+ base_url: str = BASE_URL,
75
+ transport: httpx.BaseTransport | None = None,
76
+ ) -> None:
77
+ self.http = HttpClient(
78
+ base_url=base_url.rstrip("/") + "/",
79
+ timeout=timeout,
80
+ max_retries=max_retries,
81
+ backoff_factor=backoff_factor,
82
+ rate_limit=rate_limit,
83
+ user_agent=user_agent,
84
+ transport=transport,
85
+ )
86
+
87
+ def close(self) -> None:
88
+ self.http.close()
89
+
90
+ def __enter__(self) -> Self:
91
+ return self
92
+
93
+ def __exit__(
94
+ self,
95
+ exc_type: type[BaseException] | None,
96
+ exc: BaseException | None,
97
+ tb: TracebackType | None,
98
+ ) -> None:
99
+ self.close()
100
+
101
+ # ================================================================== /studies
102
+
103
+ @staticmethod
104
+ def _build_query(query: StudyQuery | None, kwargs: StudyQueryParams) -> StudyQuery:
105
+ q = query or StudyQuery()
106
+ if kwargs:
107
+ q = q.replace(**kwargs)
108
+ if q.nct_only_query and q.has_filters:
109
+ warnings.warn(
110
+ "a query.* parameter contains only NCT IDs, so the API ignores all filter.*, "
111
+ "postFilter.* and aggFilters parameters",
112
+ UserWarning,
113
+ stacklevel=3,
114
+ )
115
+ return q
116
+
117
+ @staticmethod
118
+ def _paging_params(
119
+ *,
120
+ page_size: int | None,
121
+ page_token: str | None,
122
+ count_total: bool,
123
+ markup_format: MarkupFormat | None,
124
+ fmt: str,
125
+ ) -> dict[str, str]:
126
+ params = {"format": fmt}
127
+ if page_size is not None:
128
+ if page_size < 0:
129
+ raise ValueError("page_size must be >= 0")
130
+ params["pageSize"] = str(page_size)
131
+ if page_token:
132
+ params["pageToken"] = page_token
133
+ if count_total:
134
+ params["countTotal"] = "true"
135
+ if markup_format:
136
+ params["markupFormat"] = markup_format
137
+ return params
138
+
139
+ @overload
140
+ def search_studies_raw(
141
+ self,
142
+ query: StudyQuery | None = None,
143
+ *,
144
+ format: Literal["json"] = "json",
145
+ page_size: int | None = None,
146
+ page_token: str | None = None,
147
+ count_total: bool = False,
148
+ markup_format: MarkupFormat | None = None,
149
+ **kwargs: Unpack[StudyQueryParams],
150
+ ) -> PagedStudiesDict: ...
151
+
152
+ @overload
153
+ def search_studies_raw(
154
+ self,
155
+ query: StudyQuery | None = None,
156
+ *,
157
+ format: Literal["csv"],
158
+ page_size: int | None = None,
159
+ page_token: str | None = None,
160
+ count_total: bool = False,
161
+ markup_format: MarkupFormat | None = None,
162
+ **kwargs: Unpack[StudyQueryParams],
163
+ ) -> str: ...
164
+
165
+ def search_studies_raw(
166
+ self,
167
+ query: StudyQuery | None = None,
168
+ *,
169
+ format: Literal["json", "csv"] = "json",
170
+ page_size: int | None = None,
171
+ page_token: str | None = None,
172
+ count_total: bool = False,
173
+ markup_format: MarkupFormat | None = None,
174
+ **kwargs: Unpack[StudyQueryParams],
175
+ ) -> PagedStudiesDict | str:
176
+ """One page of ``GET /studies`` as the API returns it.
177
+
178
+ ``format="json"`` returns the parsed ``{"studies": [...], "nextPageToken": ...}``
179
+ dict; ``format="csv"`` returns CSV text (the total count, if requested, is in the
180
+ ``x-total-count`` header and therefore not available here — use :meth:`count_studies`).
181
+ """
182
+ response = self._fetch_page(
183
+ self._build_query(query, kwargs),
184
+ fmt=format,
185
+ page_size=page_size,
186
+ page_token=page_token,
187
+ count_total=count_total,
188
+ markup_format=markup_format,
189
+ )
190
+ if format == "csv":
191
+ return response.text
192
+ return cast("PagedStudiesDict", response.json())
193
+
194
+ def _fetch_page(
195
+ self,
196
+ q: StudyQuery,
197
+ *,
198
+ fmt: str,
199
+ page_size: int | None,
200
+ page_token: str | None,
201
+ count_total: bool,
202
+ markup_format: MarkupFormat | None,
203
+ ) -> httpx.Response:
204
+ params = {
205
+ **q.to_params(),
206
+ **self._paging_params(
207
+ page_size=page_size,
208
+ page_token=page_token,
209
+ count_total=count_total,
210
+ markup_format=markup_format,
211
+ fmt=fmt,
212
+ ),
213
+ }
214
+ return self.http.get("studies", params=params)
215
+
216
+ def search_studies(
217
+ self,
218
+ query: StudyQuery | None = None,
219
+ *,
220
+ page_size: int | None = None,
221
+ page_token: str | None = None,
222
+ count_total: bool = False,
223
+ markup_format: MarkupFormat | None = None,
224
+ **kwargs: Unpack[StudyQueryParams],
225
+ ) -> StudiesPage:
226
+ """One page of ``GET /studies`` as typed :class:`~trialmap.models.Study` objects.
227
+
228
+ Pass the returned ``next_page_token`` back as ``page_token`` together with the *same*
229
+ search parameters to get the next page — or just use :meth:`iter_studies`.
230
+ """
231
+ data = self.search_studies_raw(
232
+ query,
233
+ page_size=page_size,
234
+ page_token=page_token,
235
+ count_total=count_total,
236
+ markup_format=markup_format,
237
+ **kwargs,
238
+ )
239
+ return StudiesPage(
240
+ studies=tuple(Study.from_raw(s) for s in data.get("studies", [])),
241
+ next_page_token=data.get("nextPageToken"),
242
+ total_count=data.get("totalCount"),
243
+ )
244
+
245
+ def iter_pages(
246
+ self,
247
+ query: StudyQuery | None = None,
248
+ *,
249
+ page_size: int = MAX_PAGE_SIZE,
250
+ max_studies: int | None = None,
251
+ count_total: bool = False,
252
+ markup_format: MarkupFormat | None = None,
253
+ **kwargs: Unpack[StudyQueryParams],
254
+ ) -> Iterator[PagedStudiesDict]:
255
+ """Yield raw result pages, following ``nextPageToken`` until the last page.
256
+
257
+ ``max_studies`` stops after that many studies in total (the last page is requested
258
+ with a smaller ``pageSize`` so no data is fetched and thrown away).
259
+ """
260
+ if max_studies is not None and max_studies <= 0:
261
+ return
262
+ q = self._build_query(query, kwargs)
263
+ page_size = min(max(page_size, 1), MAX_PAGE_SIZE)
264
+ token: str | None = None
265
+ seen = 0
266
+ while True:
267
+ size = page_size if max_studies is None else min(page_size, max_studies - seen)
268
+ page = cast(
269
+ "PagedStudiesDict",
270
+ self._fetch_page(
271
+ q,
272
+ fmt="json",
273
+ page_size=size,
274
+ page_token=token,
275
+ count_total=count_total and token is None,
276
+ markup_format=markup_format,
277
+ ).json(),
278
+ )
279
+ studies = page.get("studies", [])
280
+ if max_studies is not None and seen + len(studies) > max_studies:
281
+ page = {**page, "studies": studies[: max_studies - seen]}
282
+ seen += len(page.get("studies", []))
283
+ log.debug("page: %d studies (total so far %d)", len(studies), seen)
284
+ yield page
285
+ token = page.get("nextPageToken")
286
+ # A page may legitimately be empty; only a missing token marks the end.
287
+ if not token or (max_studies is not None and seen >= max_studies):
288
+ return
289
+
290
+ @overload
291
+ def iter_studies(
292
+ self,
293
+ query: StudyQuery | None = None,
294
+ *,
295
+ raw: Literal[False] = False,
296
+ page_size: int = MAX_PAGE_SIZE,
297
+ max_studies: int | None = None,
298
+ markup_format: MarkupFormat | None = None,
299
+ **kwargs: Unpack[StudyQueryParams],
300
+ ) -> Iterator[Study]: ...
301
+
302
+ @overload
303
+ def iter_studies(
304
+ self,
305
+ query: StudyQuery | None = None,
306
+ *,
307
+ raw: Literal[True],
308
+ page_size: int = MAX_PAGE_SIZE,
309
+ max_studies: int | None = None,
310
+ markup_format: MarkupFormat | None = None,
311
+ **kwargs: Unpack[StudyQueryParams],
312
+ ) -> Iterator[StudyDict]: ...
313
+
314
+ def iter_studies(
315
+ self,
316
+ query: StudyQuery | None = None,
317
+ *,
318
+ raw: bool = False,
319
+ page_size: int = MAX_PAGE_SIZE,
320
+ max_studies: int | None = None,
321
+ markup_format: MarkupFormat | None = None,
322
+ **kwargs: Unpack[StudyQueryParams],
323
+ ) -> Iterator[Study] | Iterator[StudyDict]:
324
+ """Yield every matching study across all pages.
325
+
326
+ >>> for s in ct.iter_studies(query_spons='"National Cancer Institute"', # doctest: +SKIP
327
+ ... filter_overall_status=[Status.RECRUITING]):
328
+ ... ...
329
+
330
+ Args:
331
+ raw: yield the JSON dicts instead of :class:`~trialmap.models.Study` objects.
332
+ page_size: studies per request (max 1000).
333
+ max_studies: stop after this many studies.
334
+ """
335
+ pages = self.iter_pages(
336
+ query,
337
+ page_size=page_size,
338
+ max_studies=max_studies,
339
+ markup_format=markup_format,
340
+ **kwargs,
341
+ )
342
+ if raw:
343
+ return (s for page in pages for s in page.get("studies", []))
344
+ return (Study.from_raw(s) for page in pages for s in page.get("studies", []))
345
+
346
+ def count_studies(
347
+ self, query: StudyQuery | None = None, **kwargs: Unpack[StudyQueryParams]
348
+ ) -> int:
349
+ """Number of studies matching a search (one small request)."""
350
+ q = self._build_query(query, kwargs).replace(fields=["NCTId"])
351
+ response = self._fetch_page(
352
+ q, fmt="json", page_size=1, page_token=None, count_total=True, markup_format=None
353
+ )
354
+ return int(response.json().get("totalCount", 0))
355
+
356
+ # ================================================================== /studies/{nctId}
357
+
358
+ @overload
359
+ def get_study_raw(
360
+ self,
361
+ nct_id: str,
362
+ *,
363
+ format: Literal["json"] = "json",
364
+ fields: str | Sequence[str] | None = None,
365
+ markup_format: MarkupFormat | None = None,
366
+ ) -> StudyDict: ...
367
+
368
+ @overload
369
+ def get_study_raw(
370
+ self,
371
+ nct_id: str,
372
+ *,
373
+ format: Literal["fhir.json"],
374
+ fields: str | Sequence[str] | None = None,
375
+ markup_format: MarkupFormat | None = None,
376
+ ) -> dict[str, Any]: ...
377
+
378
+ @overload
379
+ def get_study_raw(
380
+ self,
381
+ nct_id: str,
382
+ *,
383
+ format: Literal["csv", "ris"],
384
+ fields: str | Sequence[str] | None = None,
385
+ markup_format: MarkupFormat | None = None,
386
+ ) -> str: ...
387
+
388
+ @overload
389
+ def get_study_raw(
390
+ self,
391
+ nct_id: str,
392
+ *,
393
+ format: Literal["json.zip"],
394
+ fields: str | Sequence[str] | None = None,
395
+ markup_format: MarkupFormat | None = None,
396
+ ) -> bytes: ...
397
+
398
+ def get_study_raw(
399
+ self,
400
+ nct_id: str,
401
+ *,
402
+ format: SingleStudyFormat = "json",
403
+ fields: str | Sequence[str] | None = None,
404
+ markup_format: MarkupFormat | None = None,
405
+ ) -> StudyDict | dict[str, Any] | str | bytes:
406
+ """``GET /studies/{nctId}`` in any supported format.
407
+
408
+ Alias NCT IDs are redirected (HTTP 301) to the current record automatically.
409
+ Raises :class:`~trialmap.exceptions.NotFoundError` for unknown IDs.
410
+ """
411
+ params: dict[str, str] = {"format": format}
412
+ if fields:
413
+ params["fields"] = _serialise(fields)
414
+ if markup_format:
415
+ params["markupFormat"] = markup_format
416
+ response = self.http.get(f"studies/{nct_id.strip().upper()}", params=params)
417
+ if format in ("json", "fhir.json"):
418
+ return cast("dict[str, Any]", response.json())
419
+ if format == "json.zip":
420
+ return response.content
421
+ return response.text
422
+
423
+ def get_study(
424
+ self,
425
+ nct_id: str,
426
+ *,
427
+ fields: str | Sequence[str] | None = None,
428
+ markup_format: MarkupFormat | None = None,
429
+ ) -> Study:
430
+ """``GET /studies/{nctId}`` as a typed :class:`~trialmap.models.Study`."""
431
+ return Study.from_raw(
432
+ self.get_study_raw(nct_id, fields=fields, markup_format=markup_format)
433
+ )
434
+
435
+ # ================================================================== metadata
436
+
437
+ def metadata(
438
+ self, *, include_indexed_only: bool = False, include_historic_only: bool = False
439
+ ) -> list[FieldNodeDict]:
440
+ """``GET /studies/metadata``: the tree of every field in the study data structure."""
441
+ params = {}
442
+ if include_indexed_only:
443
+ params["includeIndexedOnly"] = "true"
444
+ if include_historic_only:
445
+ params["includeHistoricOnly"] = "true"
446
+ return cast("list[FieldNodeDict]", self.http.get("studies/metadata", params=params).json())
447
+
448
+ def search_areas(self) -> list[SearchDocumentDict]:
449
+ """``GET /studies/search-areas``: which fields each ``query.*`` parameter searches."""
450
+ return cast("list[SearchDocumentDict]", self.http.get("studies/search-areas").json())
451
+
452
+ def enums(self) -> list[EnumInfoDict]:
453
+ """``GET /studies/enums``: every enum type, its values and the fields that use it."""
454
+ return cast("list[EnumInfoDict]", self.http.get("studies/enums").json())
455
+
456
+ # ================================================================== /stats
457
+
458
+ def size_stats(self) -> GzipStatsDict:
459
+ """``GET /stats/size``: distribution of gzipped study record sizes."""
460
+ return cast("GzipStatsDict", self.http.get("stats/size").json())
461
+
462
+ def field_values(
463
+ self,
464
+ fields: str | Sequence[str] | None = None,
465
+ *,
466
+ types: FieldStatsType | str | Sequence[FieldStatsType | str] | None = None,
467
+ ) -> list[FieldValuesStatsDict]:
468
+ """``GET /stats/field/values``: value statistics (top values, counts) per leaf field."""
469
+ params = {}
470
+ if fields:
471
+ params["fields"] = _serialise(fields)
472
+ if types:
473
+ params["types"] = _serialise(types)
474
+ return cast(
475
+ "list[FieldValuesStatsDict]", self.http.get("stats/field/values", params=params).json()
476
+ )
477
+
478
+ def field_sizes(self, fields: str | Sequence[str] | None = None) -> list[ListSizesDict]:
479
+ """``GET /stats/field/sizes``: size statistics for list/array fields."""
480
+ params = {"fields": _serialise(fields)} if fields else {}
481
+ return cast("list[ListSizesDict]", self.http.get("stats/field/sizes", params=params).json())
482
+
483
+ # ================================================================== /version
484
+
485
+ def version(self) -> VersionDict:
486
+ """``GET /version``: API version and data timestamp."""
487
+ return cast("VersionDict", self.http.get("version").json())